chain-signer

chain-signer

一套面向 AI Agent 的安全工具——在危险行为发生之前将其拦截的安全带。 包含三个独立可调用的防护工具（也可作为 MCP 工具使用），可与任何钱包或身份体系配合使用：

• preflight(tx) — 解码未签名的交易，并在签名前标记资金清空风险（无限额/大额授权、授权所有资产、token 和 NFT 的 transferFrom、代理升级、链上许可、链上 Permit2 approve/permit/transferFrom、多调用中隐藏的授权，包括 Uniswap 路由器批处理和 Multicall3 aggregate/aggregate3/aggregate3Value（每条 EVM 链上的批处理辅助工具）、封装在 ERC-4337/智能账户 execute/executeBatch 中的授权、Gnosis Safe multiSend/execTransaction 和 DSProxy execute、通过 Uniswap Universal Router 转发的资金清空操作（包括 Permit2 permit/transferFrom 命令及子计划）、带有重定向输出或零滑点的 1inch AggregationRouter v5 swap()、零滑点的 0x ExchangeProxy transformERC20()、EIP-7702 账户委托，以及必然回滚的交易）。
• inspect_typed_data(td) — 在 Agent 签署 EIP-712 消息前，捕获许可钓鱼（ERC-2612、Uniswap Permit2，包括 SignatureTransfer 和 witness 变体、DAI 风格的许可），以及转移资产的 Seaport 订单——对价为零、收益转给第三方，或隐藏在 BulkOrder 树中。
• check_action(action, policy) — 在 Agent 执行操作前，强制执行允许/禁止规则，以及金额/接收方限制。

这三项防护都会安全失败，但它们只是防护措施，并非保证。此外还捆绑了一个非托管多链钱包（创建临时钱包、查询余额、发送、兑换）——Agent 持有自己的密钥并在本地签名。无需 MetaMask、无需账户、无需托管。

from chain_signer import assert_safe
assert_safe(tx)   # raises if the tx is a drain/unlimited-approval/revert — review before signing

安装

pip install chain-signer
export ETHERSCAN_API_KEY=...   # for live balance reads + broadcast (Etherscan v2)

Bitcoin/Solana 支持为可选项：pip install "chain-signer[all]"。

快速开始（10 秒——离线、无需密钥、无需资金、无需网络）

pip install chain-signer

from chain_signer import preflight
spender = "0x" + "22" * 20
tx = {"to": "0x" + "33" * 20, "data": "0x095ea7b3" + spender[2:].rjust(64, "0") + "f" * 64, "value": 0}
print(preflight(tx))   # ok=False — flags unlimited_approval before you'd ever sign

这正是关键所在：资金清空风险会在你签名前被标记——无需密钥、无需资金、无需网络。

内置钱包（可选——这些防护可与任何钱包配合使用）

from chain_signer import burner, send_ether
from chain_signer.balance import get_balance

w = burner()                          # fresh throwaway wallet; the agent owns w.private_key
print(w.address, get_balance(w))      # live on-chain balance
send_ether(w, "0x...recipient", 0.001)  # auto nonce+gas, signed locally, broadcast

仓库中提供了可直接运行的完整演示：examples/agent_safety_demo.py（三项防护分别阻止三种真实攻击）和 examples/quickstart.py（钱包）——克隆仓库即可运行，也可以像上面那样直接导入。

安全预检（切入点）

Agent 签名之前，将未签名的交易交给 preflight() — 它会解码 calldata 并返回 风险；也可以使用 assert_safe() 在出现 HIGH 标记时强制停止。离线运行，无需联网，永不抛出异常。

from chain_signer import preflight, assert_safe

# an unlimited-allowance approve() to a spender — the classic drain setup
tx = {"to": token, "data": "0x095ea7b3" + spender_padded + "f"*64, "value": 0}

report = preflight(tx)
# {'decoded': {...}, 'ok': False,
#  'risk_flags': [{'code': 'unlimited_approval', 'severity': 'HIGH',
#                  'detail': 'approve() grants an effectively-unlimited allowance ...'}]}

assert_safe(tx)          # raises ValueError on a HIGH flag; pass force=True to override
assert_safe(tx, sim=my_simulator)   # optional: also flag will-revert via your simulation hook

目前会标记的风险：无限/大额授权、increaseAllowance、setApprovalForAll、 ERC-20 transferFrom + ERC-721/1155 safeTransferFrom（代币和 NFT 提取），ERC-777 authorizeOperator/operatorSend （授予操作员权限 + 操作员提取），链上 ERC-2612 和 DAI 风格的 permit， 链上 Permit2 approve/permit/transferFrom（单笔及批量 — 占主导地位的授权路由器： 无限 uint160 额度 + 提取），以及 Permit2 SignatureTransfer permit(Witness)TransferFrom （一次性签名许可提取意图/填充器协议使用），代理 upgradeTo/upgradeToAndCall，隐藏在 multicall（所有路由器 变体，包括嵌套调用）和 Multicall3 aggregate/aggregate3/aggregate3Value 中的授权（这是在每条 EVM 链上都部署于同一地址的标准批处理 辅助工具），封装在 ERC-4337/智能账户 execute/executeBatch、Gnosis Safe multiSend/execTransaction 或 DSProxy execute(target,data)/execute(code,data) 中的授权（会解码并递归检查）， 经 Uniswap Universal Router 路由的资产提取 （execute(commands,inputs) — Permit2 permit/transferFrom 命令、批量处理和 EXECUTE_SUB_PLAN）， EIP-7702 账户委托（“钱包升级”提取器）、大额原生币转账、 不透明 calldata、格式错误的调用，以及将会回滚的调用（带模拟钩子）。 合理的限制（请务必阅读）：这是静态分析 — 它会解码 calldata 并匹配已知的资产提取 模式。它不是交易模拟器：无法检测无法解码的新型/混淆资产提取（这类情况会标记为低严重性“未知”，而非拦截），基于模拟的扫描器在这方面能做更深入的检查。 目前安全覆盖仅限 EVM（不分析 Solana/Bitcoin 交易）。而且尚未经过大规模实地验证。它是针对已知模式的第一道防线 — 并非保证安全。对于高价值操作，应结合模拟和人工 审查。

签名消息检查器（链下部分）

资产提取不需要交易。DApp 可以要求 Agent 签署 EIP-712 消息 — 最危险的是授予无限代币额度的 permit，这是交易检查工具 preflight 无法发现的。inspect_typed_data() 会在 Agent 签名前捕获此类风险：

from chain_signer import inspect_typed_data
report = inspect_typed_data(typed_data)   # the EIP-712 object you're about to sign
# ok=False, risk_flags=[{'code': 'unlimited_permit_signature', 'severity': 'HIGH', ...}]

覆盖三种主要的 permit 类型：ERC-2612、Uniswap Permit2（PermitSingle/PermitBatch，以及 SignatureTransfer 和意图协议使用的 witness 变体），以及 DAI 风格（allowed: true）， 还包括会让资产白白转出的 Seaport 市场订单 — 对价为零、收益被转给第三方而你的资产离开，或同样的赠送行为被埋在 BulkOrder Merkle 树中。 离线运行，永不抛出异常。

受保护的签名器（检查并一次完成签名）

只有 Agent 记得先调用 inspect_typed_data 时，它才会受到保护 — 单独调用 sign_typed_data 会直接签署用于许可钓鱼的消息。guarded_sign_typed_data() 将两者组合起来，让签名默认经过检查：它会检查消息，然后拒绝签署具有 HIGH 风险的资产提取消息。

from chain_signer import guarded_sign_typed_data, SignatureBlocked
sig = guarded_sign_typed_data(wallet, domain, types, message, "Permit")  # raises SignatureBlocked on a drain

对于安全的消息，生成的签名与 sign_typed_data 完全相同；传入 force=True 可覆盖此限制。

操作策略门控（检查 Agent 执行的操作）

身份能告诉你 Agent 是谁；但无法阻止不良的操作。check_action() 会在建议的工具调用运行前执行 策略 — 默认安全（无法读取输入时拒绝操作）：

from chain_signer import check_action
policy = {"forbid_tools": ["bridge"], "max_value_wei": 10**18, "allow_recipients": [trusted_addr]}
r = check_action({"tool": "send", "args": {"to": addr, "value_wei": 5*10**18}}, policy)
# {'allowed': False, 'violations': [{'code': 'value_over_limit', ...}]}

这三种防护都作为 MCP 工具公开（preflight、inspect_signature、check_action）— 任何 Agent 运行时（Claude、Cursor、…）都可以直接调用；只读，无需密钥。

了解能捕获和无法捕获的内容 — 请参阅如实呈现威胁覆盖范围的说明：docs/THREAT-COVERAGE.md。

你将获得

• preflight(tx) / assert_safe(tx) — 解码未签名的交易，并在签名前标记资金清空模式。
• inspect_typed_data(td) — 在 Agent 签署 EIP-712 消息前，标记许可钓鱼行为。
• guarded_sign_typed_data(w, domain, types, message, primary_type) — 先筛查再签名；拒绝资金清空操作。
• check_action(action, policy) — 在 Agent 执行操作前，强制执行允许/禁止规则，以及金额/接收方限制。
• burner() — 为一次性任务创建一个全新的钱包；完成后将其丢弃。
• restore(key) — 之后通过导出的私钥重新加载钱包（同一密钥 → 同一地址）。
• send_ether(w, to, amount) — 以 ETH（而非 wei）发送；为你处理 nonce、gas 和广播。
• get_balance(w) — 获取链上的实时余额（使用 Etherscan v2 索引器，而非不稳定的公共 RPC）。
• swap(...) — 通过 0x/Paraswap 进行代币兑换。
• 通过 [all] extra 可选启用 Solana + Bitcoin 钱包。

非托管保证

私钥在本地生成/加载，仅用于签名，且绝不会被此库记录日志、返回或存储。密钥由你保管；我们绝不会接触你的资金。这就是全部设计理念。

密钥处理（请阅读）

w.private_key 就是钱包的密钥。请像对待密码一样妥善保管：

• 绝不要记录它、在生产环境中打印它，或将它写入笔记/记忆/聊天内容。任何持有它的人都能控制资金。
• 按设计，用于存放少量资金的 burner 风险较低，但仍须遵守此规则。
• 如需稍后重复使用钱包，请将密钥存入密钥管理器/环境变量，然后调用 restore(key)。
• 更好的做法是：export_encrypted(w, password) 会生成受密码保护的 keystore 字典，供你静态存储；load_encrypted(keystore, password) 可恢复钱包。只要能存储 keystore，就不要存储原始密钥。

签名惯用方式（web3.py 用户请注意）

钱包不提供 sign_transaction / sign_message 方法。签名通过接收钱包作为参数的函数辅助程序完成，例如 send_ether(w, to, amount) 会签名并广播，而 sign_message(w, "text") 会返回用于身份验证/登录流程的 EIP-191 签名（可通过 eth_account Account.recover_message 恢复）。

PATH 中的 CLI

pip install 可能会提示 chain-signer 脚本目录不在你的 PATH 中。库仍可正常工作；如需直接使用 CLI，请将该目录添加到 PATH，或运行 python -m chain_signer ...。

工具接口（适用于任何 AI / MCP / CLI）

chain_signer.mcp_server 提供 list_tools() 和 call_tool(name, arguments)。CLI：

python -m chain_signer list
python -m chain_signer call create_wallet '{"chain":"evm"}'

负责任地使用

这是通用的非托管工具。你有责任确保使用方式符合适用于你的法律和服务条款。本工具并非为你所在司法管辖区内受限制或禁止的交易而设计或推广。

注意事项

• 余额查询/广播使用 Etherscan v2 索引器（权威来源），绝不使用免费的公共 RPC。
• 低级构建模块（tx.send、call_contract、显式 nonce/gas）仍可供高级用途使用。

一次调用即可支付 x402 API

from chain_signer import burner, sign_x402_payment
w = burner()
payload = sign_x402_payment(w, token=USDC, to=PAY_TO, value=1000, valid_before=EXPIRES, chain_id=8453)
# -> {"signature", "authorization"} ready for the x402 payment header. Signed locally, no prompt.

构建并签署 x402 所需的 EIP-3009 授权（“exact”方案）。你的 Agent 可自行向付费 API 付款——无需输入密码、注册或托管。

签署 typed data（EIP-712）——用于 Agent 付款 / x402

from chain_signer import burner, sign_typed_data
w = burner()
sig = sign_typed_data(w, domain, types, message)  # EIP-712; for x402 / EIP-3009 authorizations

你的 Agent 可在本地签署 typed data 来授权付款——无需输入密码或注册。

作为 MCP 服务运行

chain-signer 也是 Model Context Protocol（MCP）服务，因此支持 MCP 的 Agent 可以直接使用它：

pip install chain-signer
chain-signer-mcp          # speaks MCP over stdio (JSON-RPC 2.0)

提供 9 个工具。三个安全防护工具（安全楔）：preflight、inspect_signature、check_action。还有非托管钱包：create_wallet、get_balance、send、call_contract、swap、bridge。

将其添加到客户端的 mcpServers 配置中，即可接入任何 MCP 客户端（Claude Desktop、Cursor 等）：

{
  "mcpServers": {
    "chain-signer": {
      "command": "chain-signer-mcp",
      "env": { "ETHERSCAN_API_KEY": "your-key-for-live-balance-and-broadcast" }
    }
  }
}

就是这样——现在，Agent 可以在执行任何操作前，通过这些防护工具检查每笔交易、签名和操作；还可以（可选）持有自己的钱包，将读取余额、发送和兑换作为原生工具使用。 （ETHERSCAN_API_KEY 为可选项；仅在实时读取余额和广播交易时需要。）