内容
# 链签名工具
<!-- mcp-name: io.github.Kevthetech143/chain-signer -->
   
人工智能代理的安全套件 — 在危险发生之前捕获的保护带。
三个守卫，每个都可以单独调用（并且作为MCP工具），与任何钱包或身份栈配对：
- `preflight(tx)` — 解码未签名的交易并在签名前标记资金流出（无限/大额批准，批准所有，代币和NFT transferFrom，代理升级，链上许可，链上Permit2批准/许可/transferFrom，隐藏在multicall中的批准，包括Uniswap路由器批次和Multicall3聚合/聚合3/聚合3Value（每个EVM链上的批次助手），ERC-4337/smart-account执行/executeBatch，Gnosis Safe multiSend/execTransaction和DSProxy执行，资金流出通过Uniswap通用路由器（Permit2许可/transferFrom命令，包括子计划），1inch AggregationRouter v5交换（）具有重定向输出或零滑点，0x ExchangeProxy transformERC20（）具有零滑点，EIP-7702账户委托，will-revert）。
- `inspect_typed_data(td)` — 在代理签名之前捕获EIP-712消息中的permit-phishing（ERC-2612，Uniswap Permit2包括SignatureTransfer + witness变体，DAI-style许可）和Seaport订单，给予资产 - 零考虑，收益路由给第三方，或隐藏在BulkOrder树中。
- `check_action(action, policy)` — 在代理执行之前强制执行allow/forbid + value/recipient限制。
所有三个都是安全的守护者，而不是保证。还包括一个非托管的多链钱包（烧钱钱包，余额，发送，交换）- 代理持有自己的密钥并在本地签名。没有MetaMask，没有账户，没有托管。
```python
from chain_signer import assert_safe
assert_safe(tx) # 如果交易是资金流出/无限批准/回滚 - 审查后签名
```
## 安装
```
pip install chain-signer
export ETHERSCAN_API_KEY=... # 用于实时余额读取 + 广播（Etherscan v2）
```
比特币/索拉纳支持是可选的：`pip install "chain-signer[all]"`。
## 快速入门（10秒 - 离线，无密钥，无资金，无网络）
```
pip install chain-signer
```
```python
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 - 在您签名之前标记无限批准
```
这就是楔形：资金流出在您签名之前被标记 - 无密钥，无资金，无网络。
### 捆绑钱包（可选 - 守护者与任何钱包配对）
```python
from chain_signer import burner, send_ether
from chain_signer.balance import get_balance
w = burner() # 新的临时钱包；代理拥有w.private_key
print(w.address, get_balance(w)) # 实时链上余额
send_ether(w, "0x...recipient", 0.001) # 自动nonce+gas，本地签名，广播
```
完整的演示在仓库中：`examples/agent_safety_demo.py`（所有三个守护者停止三个真实攻击）和`examples/quickstart.py`（钱包）- 克隆运行它们，或直接导入。
## 安全预检（楔形）
在代理签名之前，将未签名的交易交给`preflight()` - 它解码调用数据并返回风险，或使用`assert_safe()`在高风险标志上硬停止。离线，无网络，永不引发。
```python
from chain_signer import preflight, assert_safe
# 无限批准的approve() - 经典的资金流出设置
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()授予一个有效的无限额度...'}]}
assert_safe(tx) # 在高风险标志上引发ValueError；传递force=True以覆盖
assert_safe(tx, sim=my_simulator) # 可选：还通过模拟钩子标记will-revert
```
今日标记的内容：无限/大额批准，`increaseAllowance`，`setApprovalForAll`，ERC-20 `transferFrom` + ERC-721/1155 `safeTransferFrom`（代币和NFT资金流出），ERC-777 `authorizeOperator`/`operatorSend`（操作员授予+操作员拉取资金流出），链上ERC-2612和DAI-style `permit`，链上Permit2 `approve`/`permit`/`transferFrom`（单个**和**批量 - 主导批准路由器：无限uint160额度+资金流出拉取）以及Permit2 SignatureTransfer `permit（Witness）TransferFrom`（一次性签名许可拉取意图/填充协议使用），代理`upgradeTo`/`upgradeToAndCall`，隐藏在`multicall`（所有路由器变体，嵌套）**和Multicall3 `aggregate`/`aggregate3`/`aggregate3Value`**（规范的批量助手，部署在每个EVM链上的一个地址），ERC-4337/smart-account `execute`/`executeBatch`，Gnosis Safe `multiSend`/`execTransaction`，或DSProxy `execute（target，data）`/`execute（code，data）`（解码和递归），通过Uniswap **通用路由器**
（`execute（commands，inputs）` - Permit2 `permit`/`transferFrom`命令，批量和`EXECUTE_SUB_PLAN`），EIP-7702账户委托（“钱包升级”资金流出器），大额原生价值，不透明的调用数据，格式错误调用，以及will-revert（带有模拟钩子）。
诚实的限制（阅读这些）：这是**静态**分析 - 它解码调用数据并匹配已知的资金流出模式。它**不是**交易模拟器：它不会捕获它无法解码的新颖/伪装的资金流出（那些获得低风险“未知”标志，而不是阻止），基于模拟的扫描器在那里更深入。安全覆盖仅限于EVM（无Solana/Bitcoin交易分析）。而且它尚未在规模上经过实证检验。第一个防范已知模式的守护者 - **不是**保证。与模拟+人工审查配对高价值操作。
## 签名消息检查（离线半部分）
资金流出不一定需要交易。 dApp可以要求代理**签名** EIP-712消息 -
最危险的是`permit`授予无限代币额度，`preflight`（交易检查）看不到。`inspect_typed_data（）`在代理签名之前捕获它：
```python
from chain_signer import inspect_typed_data
report = inspect_typed_data(typed_data) # 您即将签名的EIP-712对象
# ok=False, risk_flags=[{'code': 'unlimited_permit_signature', 'severity': 'HIGH', ...}]
```
涵盖三种主要的许可形状：**ERC-2612**，**Uniswap Permit2**（PermitSingle/PermitBatch，以及SignatureTransfer和witness变体意图协议使用），和**DAI-style**（`allowed：true`），以及**Seaport**市场订单，免费赠送资产 - 零考虑，收益路由给第三方，或相同的免费赠送行为埋在BulkOrder merkle树中。离线，永不引发。
### 受保护的签名者（屏幕+签名一步）
`inspect_typed_data`仅在代理记住首先调用它时保护 - `sign_typed_data`
愿意签名permit-phishing消息。`guarded_sign_typed_data（）`组合这两个，因此签名默认情况下受到保护：
```python
from chain_signer import guarded_sign_typed_data, SignatureBlocked
sig = guarded_sign_typed_data(wallet, domain, types, message, "Permit") # 在资金流出时引发SignatureBlocked
```
在干净的消息上，签名与`sign_typed_data`字节相同；传递`force=True`以覆盖。
## 动作策略门（检查代理执行的操作）
身份告诉你**谁**是代理 - 它不阻止一个坏的**操作**。`check_action（）`在提案的工具调用运行之前强制执行一个策略 - 故障安全（拒绝不可读的输入）：
```python
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`）- 任何代理运行时（Claude，Cursor，...）都可以直接调用它们，读-only，无密钥。
## 您获得什么
- `preflight(tx)` / `assert_safe(tx)` — 解码未签名的交易并在签名前标记资金流出模式。
- `inspect_typed_data(td)` — 在代理签名EIP-712消息之前标记permit-phishing。
- `guarded_sign_typed_data(w, domain, types, message, primary_type)` — 筛选然后签名；拒绝资金流出。
- `check_action(action, policy)` — 在代理执行之前强制执行allow/forbid + value/recipient限制。
- `burner()` — 用于一次性任务的新钱包；使用后丢弃。
- `restore(key)` — 从其导出的私钥重新加载钱包（相同密钥→相同地址）。
- `send_ether(w, to, amount)` — 以ETH（非wei）发送；自动处理nonce，gas和广播。
- `get_balance(w)` — 来自链的实时余额（Etherscan v2索引器，非脆弱的公共RPC）。
- `swap(...)` — 通过0x/Paraswap进行代币交换。
- 可选的Solana + Bitcoin钱包通过`[all]`额外功能。
## 非托管保证
私钥在本地生成/加载，仅用于签名，永远不会被此库记录，返回或存储。您持有密钥；我们永远不会触摸您的资金。就是这样。
## 处理密钥（阅读此内容）
`w.private_key`是钱包的密钥。像密码一样对待它：
- **永远不要**在生产中记录它，打印它，或将其写入笔记/内存/聊天中。任何拥有它的人都可以控制资金。
- 对于持有少量美元的烧钱钱包来说，这是低风险的，但规则仍然适用。
- 要重用钱包，请将密钥存储在秘密管理器/环境变量中，然后`restore(key)`。
- 更好：`export_encrypted(w, password)`给出了一个密码保护的密钥存储字典来存储；`load_encrypted(keystore, password)`将钱包恢复。永远不要存储原始密钥，如果可以存储密钥存储。
## 签名习惯（适用于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支付一步
```python
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"} 准备好用于x402支付头部。本地签名，无提示。
```
构建并签名x402期望的EIP-3009授权（“exact”方案）。您的代理支付付费API - 无密码提示，无注册，无托管。
## 签名类型数据（EIP-712）- 用于代理支付/x402
```python
from chain_signer import burner, sign_typed_data
w = burner()
sig = sign_typed_data(w, domain, types, message) # EIP-712；用于x402 / EIP-3009授权
```
您的代理可以通过签名类型数据本地授权付款 - 无密码提示，无注册。
## 作为MCP服务器运行
chain-signer也是一个模型上下文协议（MCP）服务器，因此MCP感知代理可以直接使用它：
```
pip install chain-signer
chain-signer-mcp # 通过stdio（JSON-RPC 2.0）公开MCP
```
公开9种工具。三个安全守护者（楔形）：`preflight`，`inspect_signature`，
`check_action`。另外，非托管钱包：create_wallet，get_balance，send，call_contract，swap，bridge。
通过将其添加到客户端的`mcpServers`配置中，将其连接到任何MCP客户端（Claude Desktop，Cursor等）：
```json
{
"mcpServers": {
"chain-signer": {
"command": "chain-signer-mcp",
"env": { "ETHERSCAN_API_KEY": "your-key-for-live-balance-and-broadcast" }
}
}
}
```
就是这样 - 代理现在可以通过守护者筛选每笔交易，签名和操作（可选）持有自己的钱包来读取余额，发送和交换作为原生工具。
（`ETHERSCAN_API_KEY`是可选的；仅需要实时余额读取和广播。）
