agentic-wallet-guardian-v3

Agentic Wallet Guardian

观看演示

选择预览图，即可在浏览器中播放视频。

📄 阅读白皮书

让 AI Agent 在链上执行交易，而无需赋予它们对钱包的无限制控制权。 Guardian 会在签名或广播前评估每项待执行操作，并返回可解释的 ALLOW / WARN / BLOCK 决策。

POST /decision   ->   ALLOW / WARN / BLOCK  (with a reasoned explanation)

它运行在你自己的基础设施上，使用你自己的策略规则和信誉数据——请参阅为何选择可自托管，了解这样做的重要性，以及这与直接调用托管安全 API 有何不同。

Guardian 不受特定链或用例限制——下文的 Arc/USDC 只是一个正在运行的部署，并非全部适用范围。请参阅 docs/hackathons.md，了解本次提交面向的赛道及原因。

Arc 主网演示

在线演示： http://77.239.125.37:8765/arc

演示视频： https://youtu.be/srH0ZLwtwqQ

Agentic Wallet Guardian 已部署在 Arc 主网上，并提供用于 USDC 支付的实时浏览器演示。Guardian 会在执行前评估请求的操作，应用其安全策略，并仅将获批的操作交由用户的钱包签名。

已验证的 Arc 主网交易： 0xd781e8b04b5ca89c3a34fcec50a6636049f7647d2b0e1b2bb64d5b1ee54daadf

该交易已通过 Guardian 演示，使用 USDC 在 Arc 主网上成功执行。

---

**实时查看决策过程：**在本地运行 API（GUARDIAN_ENABLE_CORS_FOR_BROWSER_DEMO=true uvicorn api.main:app --reload），然后在浏览器中打开 examples/browser-demo.html——无需构建，也无需为页面本身启动服务。每个场景按钮都会向正在运行的实例发送真实的 POST /decision 请求，并显示实际响应（风险评分、参与评估的每项信号、触发的每条策略规则）——页面中的内容并非脚本编写或伪造。默认情况下，GUARDIAN_ENABLE_CORS_FOR_BROWSER_DEMO 处于关闭状态（请参阅 guardian/config.py），因为它专用于此类本地演示，不应在实际部署中保持开启。

---

选择自托管的原因

对于 Agent 交易安全，市面上有不错的托管替代方案（GoPlus 的 AgentGuard、Blockaid，以及用于合规的 Chainalysis/TRM）。如果你只想要 风险评分，也不在意谁能看到查询内容，直接调用其中一个服务，比运行本项目省事。 Guardian 适用于这种权衡对你行不通的情况：

• 你的 Agent 接触哪些钱包、合约或金额的信息，都不会离开你的基础设施。 威胁情报和合约允许/拒绝检查使用你自行填充的本地 JSON 文件（参见 data/threat_lists/README.md），而不是向第三方发起查询。 托管 API 天生就能看到你查询的每个地址和金额。
• 策略规则保存在你的代码中，而不是供应商的控制面板上。 支出上限、声誉门槛，以及哪些操作类型需要确认，都是 guardian/policy/ 中的纯 Python 代码，可供审查和修改，无需等待他人的产品路线图。
• 没有他人施加的按次调用费用或速率限制——只有你为自己的用户配置的限制（GUARDIAN_RATE_LIMIT_PER_MINUTE）。
• 没有供应商锁定。 每个外部数据源（RPC 端点、 Blockscout 实例、DexScreener）都可以通过一个简洁的提供程序接口进行替换——参见架构。

坦诚地说，反过来也有取舍：你还要负责运行它、及时更新本地威胁名单，而且无法免费获得托管供应商的链覆盖范围或专职威胁研究团队。对于确实需要数据主权或深度定制策略的团队来说，这是合适的选择——但并非严格优于所有托管方案。

---

架构

                AI Agent
                    |
                    v
             Action Intent
   { agent_id, wallet, chain, action_type,
     target, amount, metadata }
                    |
                    v
        ┌───────────────────────────────┐
        │   Guardian Decision Engine    │
        ├───────────────────────────────┤
        │  1. Hard Rules                │  <- chain support, sanity checks
        │  2. Wallet Intelligence       │  <- mock | real RPC (web3.py)
        │  3. Token Intelligence        │  <- mock | real DexScreener | real GoPlus
        │  4. Contract Intelligence     │  <- local lists, then mock | real Blockscout | real GoPlus
        │  5. Simulation                │  <- mock | real eth_call dry-run (see below)
        │  6. Threat Intelligence       │  <- local JSON allow/deny lists
        │  7. Anomaly Detection         │  <- vs. this agent's own history (see below)
        │  8. Policy Engine             │  <- spending caps, reputation gates
        │  9. Risk Fusion               │  <- signals -> single 0-100 score
        │ 10. Reputation Adjustment     │
        │ 11. Explanation               │  <- evidence -> human-readable reasons
        └───────────────────────────────┘
                    |
                    v
          ALLOW / WARN / BLOCK
                    |
                    v
          Blockchain Execution

步骤 2-4 中的每个数据源都是一个简洁的提供程序接口，包含模拟实现（无需配置，也不会发起网络调用）和真实实现，并通过环境变量按数据源选择——参见 .env.example。从演示模式切换到真实部署只需更改配置，无需更改代码。

仓库布局

guardian/
    config.py          GuardianConfig - the one place that reads os.environ
    core/               ActionIntent, Signal, Decision, EvaluationContext
                            (zero external dependencies - no pydantic/FastAPI)
    decision/           DecisionEngine (orchestrator), RiskFusionEngine, hard rules
    reasoning/          explanation + confidence builders
    intelligence/
        wallet/           analyzer.py + providers.py (mock | RpcWalletDataProvider)
        token/            analyzer.py + providers.py (mock | DexScreenerTokenDataProvider | GoPlusTokenDataProvider)
        contract/         analyzer.py + providers.py (mock | BlockscoutContractDataProvider | GoPlusContractDataProvider)
        simulation/       pre-execution dry-run (mock | real eth_call) + tx_builder.py (real calldata for transfer/approve)
        goplus_client.py  shared GoPlus Token Security API client (used by both contract + token)
        threat/           blocklist.py (local AddressList) + intelligence.py
    policy/             PolicyEngine + policy templates (spending caps, reputation gates)
    reputation/         AgentReputation (score derived from decision history)
    memory/             storage.py (protocol) + InMemoryStorage + sqlite_storage.py
api/
    main.py             FastAPI app: /decision, /health, /capabilities, /agents/{id}/history, /demo/{scenario}
    security.py         API-key auth dependency + rate-limit middleware
    schemas.py          pydantic request/response models (API boundary only)
mcp_server.py           MCP stdio server - same DecisionEngine, no HTTP required
data/threat_lists/      local, operator-maintained allow/deny lists (empty by default - see its README)
scripts/
    refresh_ofac_list.py   fetch OFAC's public SDN list into the local threat list
tests/                  101 tests covering the engine, policy, reputation, and every provider

guardian/* 有意不依赖任何第三方库（仅使用标准库，但真实提供程序需要 httpx 或 web3 时除外），因此决策核心可以进行单元测试、嵌入其他服务，或移植到其他 Web 框架，而无需连带引入 FastAPI。只有 api/ 会用到 pydantic/FastAPI。

---

如实说明当前状态

这是可实际运行、经过测试的决策基础设施，每种信号来源都有可用的真实（非模拟）数据源——但“可用”并不等于“切换一下就能盲目信任”。具体来说：

• 钱包（RPC 提供方）： is_contract 和 tx_count（基于 nonce）在任何 JSON-RPC 端点上都可靠。钱包年龄需要支持归档的节点，且默认关闭（GUARDIAN_RPC_ESTIMATE_AGE=false）——大多数免费的公共 RPC 端点不提供历史状态，因此此功能会安全地返回“未知”，而不是猜测。
• 合约（Blockscout 提供方）： 可针对公共 Blockscout 实例查询真实的验证状态。其确切响应架构和速率限制可能会变化——此实现会在遇到任何意外响应时降级为“未知”，绝不会捏造答案，但尚未针对生产流量进行负载测试。
• 代币（DexScreener 提供方）： 提供真实的流动性数据，但将裸代币代码与链上交易对进行匹配本质上存在歧义（许多互不相关的代币使用相同代码，诈骗者还会故意铸造相似代币）。该提供方会选择指定链上流动性最高的交易对，并报告自身的匹配置信度，而不会把猜测说成确定结果——如果歧义会造成影响，请按合约地址匹配，而不是按代码匹配。
• 合约 + 代币（GoPlus 提供方）： 提供真实的合约安全信息（所有者可抽走资金、可铸造、自毁、隐藏所有者）和交易安全信息（蜜罐、买入/卖出税、黑名单、可暂停转账、持有者集中度），数据来自 GoPlus 的 Token Security API。GoPlus 自身的静态分析一次调用即可覆盖这两类信息，因此其信号类型显著多于 Blockscout/DexScreener 各自提供的信息。它有两个实际限制：只有经过其实际分析的合约才有数据（主要是代币合约，而非通用 dApp/路由器合约）；GoPlusTokenDataProvider 需要合约地址——无法解析像 "PEPE" 这样的裸代码，因此会如实报告为无法验证，而不是猜测。
• 受制裁地址列表包含真实数据且已填充： 共有 103 个地址（100 个 EVM + 3 个 Solana），来自 OFAC 的 SDN 列表，通过 0xB10C/ofac-sanctioned-digital-currency-addresses 获取——已通过端到端验证（已知受制裁地址会通过完整流程正确触发 BLOCK），并验证列表能正确反映移除项，而不只是新增项（Tornado Cash 的地址已于 2025 年 3 月从 SDN 列表移除，现在也已正确删除）。请定期重新运行 scripts/refresh_ofac_list.py——制裁名单的变动既有新增，也有移除。
• malicious_contracts.json / verified_contracts.json 仍有意保持为空（参见 data/threat_lists/README.md）——不同于 OFAC 的制裁名单，恶意合约并没有单一的权威来源，因此是否填充这些列表取决于此实例的运营者，而不是默认添加未经验证的条目。
• 模拟是真实的，但有条件。 RpcSimulationProvider（GUARDIAN_SIMULATION_PROVIDER=rpc）会通过 eth_call/eth_estimateGas，针对当前链状态真正进行交易试运行——若发生回滚，返回的是实际原因，而非猜测；ERC-20 approve() 的额度也会从真实 calldata 中解码，而不是推断得出。调用方通过 intent.metadata["data"] 提供原始 calldata 时，此功能会启用；或者——新增——同时设置 GUARDIAN_TX_BUILDER=rpc，且意图为普通的 transfer 或 approve 时也会启用（见下一条）。尚未构建交易的 swap 意图仍然没有可供试运行的内容——Guardian 会如实报告这一情况（simulation_not_attempted），而不是猜测。
• 交易构建有意只弥补了部分差距，并非全部。 RpcTransactionBuilder（GUARDIAN_TX_BUILDER=rpc）会将语义化的 transfer/approve 意图转换为真实 calldata——它通过 RPC 获取代币实际的 decimals()，而不是假设为 18（错误假设会使金额相差几个数量级），并且刻意不内置代币地址注册表：像 "USDC" 这样的裸代码会被拒绝，而不是进行猜测，因为这里的错误地址不仅会产生错误的风险信号，还可能成为最终进入真实交易的内容。swap 仅针对 Uniswap V2 Router02 构建（这是一个不可变且广为人知的合约——函数选择器通过 Web3.keccak 在本地计算，而不是凭记忆抄写）——使用链上真实的 getAmountsOut() 报价，并要求调用方提供 max_slippage_bps（绝不设默认值，理由与上面的 decimals 相同）。一般而言，bridge 是一个开放式的 L2/桥接路由问题——协议有几十种，信任模型也大相径庭——但此模块只处理其中范围明确的一部分：通过目标链自身的官方 OP Stack 桥，将资金从 L1 存入 L2（目前支持 Base 和 Optimism——在 L1StandardBridge 上调用 depositETHTo/depositERC20To；这两个地址都经过独立交叉验证——Base 地址通过 Etherscan 的标签和 basehub.org 验证，Optimism 地址则通过官方 ethereum-optimism/superchain-registry 和另一个独立的开发工具配置验证——之后才硬编码）。 不会构建 L2 -> L1 提现——这是一个本质上不同、耗时更长的证明/挑战窗口流程，并非存款调用的变体。 对其他目的地或通过任何非规范桥接进行的操作，都会返回 None，而不是猜测。
• 意图验证现在可以真正执行约束，而不仅仅是标记。 decision/intent_verification.py 会将 Agent 声明的 approve 金额与模拟 calldata 实际编码的金额进行比较——但要进行这种比较，需要代币的 decimals()，以便在人类可读单位和原子单位之间转换。GUARDIAN_DECIMALS_PROVIDER=rpc（RpcTokenDecimalsProvider，参见 guardian/intelligence/token/decimals.py）会通过 eth_call 实际获取该值，并按（链、代币）永久缓存，因为已部署合约的 decimals() 不会改变。若保留其默认值 null，此模块原本可以发现的不匹配就会降级为如实报告“无法验证”的 WARN——这遵循的是此模块一贯的“绝不默默猜测”规则，并非遗漏了这个缺口。 如果 RpcTransactionBuilder 和此功能都配置了真实提供方，两者会共用同一缓存，而不是各自独立、未经缓存地查询同一代币。
• 存储： InMemoryStorage（默认，无需设置）、SQLiteStorage（GUARDIAN_STORAGE_BACKEND=sqlite——重启后数据仍会保留，无需外部基础设施），或 PostgresStorage（GUARDIAN_STORAGE_BACKEND=postgres + GUARDIAN_POSTGRES_DSN——适用于负载均衡器后有多个副本的场景，此时 SQLite 的单写入者模型会成为瓶颈；pip install -r requirements-postgres.txt）。已针对真实的本地 Postgres 实例进行测试，而非使用模拟实例——参见 tests/test_postgres_storage.py。如果你确实想用 Redis，仍可自行实现；MemoryBackend 只有两个方法，接口足够精简，可以对接任何后端。
• API 身份验证/速率限制有意保持精简——适用于部署在你自己的网络边界内的单个可自托管实例，而非多租户网关。如有需要，请在前面部署真正的 API 网关。
• 未经安全审计。 策略引擎和风险融合逻辑尚未由此仓库之外的任何人审查。在完成审计之前，请将 BLOCK 视为强烈信号，而非保证。 Signal 下游的所有内容——融合、策略、信誉、解释、API——都无需随着上述任一部分进一步强化而改变。这条边界才是这里真正的设计契约。

---

快速入门

零配置演示模式（模拟提供方、内存存储、无身份验证）：

pip install -r requirements.txt
uvicorn api.main:app --reload

或使用 Docker：

docker compose up --build

试试预设场景：

curl http://localhost:8000/demo/safe
curl http://localhost:8000/demo/unknown
curl http://localhost:8000/demo/malicious

或提交你自己的意图：

curl -X POST http://localhost:8000/decision \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "trading-agent-001",
        "wallet": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "chain": "ethereum",
        "action_type": "swap",
        "from_token": "ETH",
        "to_token": "USDC",
        "amount": 5
      }'

从演示模式转为真实的可自托管部署

将 .env.example 复制为 .env 并进行调整：

cp .env.example .env

真实部署至少需要设置 GUARDIAN_API_KEY（默认关闭身份验证）、GUARDIAN_STORAGE_BACKEND=sqlite（持久化），以及你希望连接到真实数据而非模拟数据的 GUARDIAN_*_PROVIDER 变量。每个选项请参阅 .env.example 中的注释；各提供方实际提供的内容，请参阅 RpcWalletDataProvider/BlockscoutContractDataProvider/DexScreenerTokenDataProvider/GoPlusContractDataProvider/GoPlusTokenDataProvider 的文档字符串。

如果多个 Agent 共用此部署，还要设置 GUARDIAN_AGENT_API_KEYS（格式：agent_id:key,agent_id2:key2）。单个 GUARDIAN_API_KEY 只能证明某个调用方持有有效密钥，却不能证明某个请求实际上来自哪个 agent_id，因为 agent_id 只是请求正文中的一个字段。任何持有共享密钥的人都可以提交任意 agent_id，并继承该 agent_id 累积的信誉和能力授权。GUARDIAN_AGENT_API_KEYS 会将每个 agent_id 绑定到专属密钥；如果同时设置了 GUARDIAN_API_KEY，它仍可作为主密钥，用于以任何 Agent 的身份操作，供管理员或测试使用。对于真正的单 Agent 部署，只设置 GUARDIAN_API_KEY 即可。

MCP（无需 HTTP）

对于使用 MCP 的 Agent 框架（LangChain、CrewAI、Claude Desktop 等），mcp_server.py 会通过标准输入/输出将同一决策引擎公开为两个工具（evaluate_action、get_agent_history）。请将 requirements-mcp.txt 与 requirements.txt 一同安装（两者会安装到同一环境中；参阅 requirements-mcp.txt 顶部的注释），然后将 MCP 客户端指向 python mcp_server.py。

---

Arc 主网支付演示

Guardian 3.2 新增了一个小型的非托管 Arc 主网功能，用于自主 USDC 支付。

• Arc 主网，链 ID 5042，官方 RPC https://rpc.mainnet.arc.io
• Arc USDC ERC-20 接口 0x3600000000000000000000000000000000000000（6 位小数）
• Guardian 在释放交易前，会执行常规的硬性规则、智能分析、模拟、策略和风险处理流程
• 此功能上的演示策略将自主支付上限设为 5 USDC，并阻止 approve/swap/bridge/contract-call 操作
• 只有 ALLOW 决策才会生成可签名交易；浏览器钱包仍是唯一的签名方
• 公共演示仅保留一个有界历史身份（arc-demo-agent），因此访客流量不会创建无界的逐 Agent 记忆键
• 在运行中的实例上打开 /arc，连接钱包、向 Guardian 发出请求，并签署生成的 Arc 支付

手动验证 Arc：

python scripts/verify_arc_mainnet.py

该脚本会检查链 ID、实时区块高度、Gas 价格以及主网 USDC 的 decimals() 调用。无需私钥。

运行测试

pip install -r requirements.txt -r requirements-chain.txt -r requirements-mcp.txt
pytest -q

RPC 和链上证明测试需要 requirements-chain.txt（web3）。requirements-mcp.txt 会安装 mcp_server.py 使用的 MCP SDK。PyJWT 和 cryptography 是核心依赖，因为 OAA 证明使用 JWT 和 Ed25519 签名。CI 安装的依赖与此完整测试环境一致。

PYTHONPATH=. python3 -m unittest discover -s tests -v

CI（.github/workflows/ci.yml）会在每次推送或 PR 时，使用 Python 3.11 和 3.12 运行完整测试套件。

---

已签名、可验证的决策（OAA）

此服务返回的每个决策——从单次策略检查到完整工作流——都会签名为 OAA（Open Agent Attestation） 令牌：一个经 Ed25519 签名的 JWT，其中封装了决策、操作和原因。

任何持有公钥的人都可以离线验证决策，无需回调颁发该决策的 Guardian 实例——这对审计人员、下游服务，或任何希望日后信任记录而不必信任生成该记录的服务端的人都很有用。

python examples/example_oaa_attestation.py
python examples/example_full_pipeline.py   # capability -> intent -> engine -> OAA

参考 OAA 实现约有 150 行（上游的 oaa.py/attestation.py），并在本项目与 agent-guardrail 之间共享，未经修改——签名格式相同，验证路径相同，不为每个项目单独分叉。

---

在 MetaMask Agent Wallet 前使用 Guardian

MetaMask Agent Wallet 的 Guard Mode / Beast Mode 会对每个 Agent 应用相同的静态支出限额和允许列表。Guardian 是其前方的第二道独立检查：在调用 mm CLI 之前，针对这个特定 Agent，判断此时的这项具体操作是否合适。

skills/guardian-check/ 是标准的 Agent Skill——与 MetaMask 自己为 mm 使用的开放格式相同（npx skills add MetaMask/agent-skills）。在任何兼容 Agent-Skills 的运行时（Claude Code、Cursor、Codex、OpenClaw）中，将其与 MetaMask 自己的 Skill 一同安装后，Agent 会在运行任何会转移资金的 mm 命令之前，调用正在运行的 Guardian 实例获取 ALLOW/WARN/BLOCK 决策——包括 mm send、mm swap、mm bridge、mm perps、mm predict trade、mm earn、mm aave、mm pay。

Guardian 不持有密钥，也不会执行任何操作——mm 仍是唯一负责签名或广播的工具。这是一个要求 Agent 先行咨询的决策关卡，而不是对 MetaMask 自身工作流的修改（目前没有公开的接入点）。

uvicorn api.main:app --reload   # run Guardian locally
export GUARDIAN_API_URL="http://localhost:8000"
python skills/guardian-check/scripts/check.py \
  --agent-id my-agent --wallet 0x... --chain ethereum \
  --action-type transfer --target 0x... --amount 50

---

从建议到强制执行：GuardianValidator

以上所有内容都只是建议——Guardian 会告知你 ALLOW/WARN/BLOCK，但调用方仍需自行选择是否遵从。对于 ERC-4337 智能账户，onchain/ 是一个真正的 ERC-7579 验证器模块，可弥补这一缺口：安装后，只有在可信 Guardian 签名者针对该项确切操作证明决策为 ALLOW 时，账户的 UserOperations 才能上链——Agent 无法跳过咨询或忽略结果。请参阅 onchain/README.md，了解为何除了 OAA 之外还需要第二种原生 EVM 签名格式（Ed25519 没有 EVM 预编译，使用纯 Solidity 验证需约 2,000,000 gas；此模块完整的 validateUserOp 仅需 27k-59k gas）、明确不在范围内的内容（WARN 永远无法通过链上验证；尚未进行专业审计），以及如何构建、测试和部署该模块——其中包括一项测试，用于验证由真实运行中的 Python（guardian/onchain_attestation.py）生成的签名，能被真正的 Solidity 合约接受，而不是由两个只彼此认可的实现完成验证。

---

路线图

1. 将模拟钱包、代币和合约分析器替换为真实数据 源。 已完成——有关“真实”目前涵盖和尚未涵盖的内容，请参阅关于当前状态的说明。
2. 接入真实的执行前模拟。 transfer/ approve 的端到端流程已完成（GUARDIAN_SIMULATION_PROVIDER=rpc + GUARDIAN_TX_BUILDER=rpc——参见 关于当前状态的说明）。 swap 需要真实的 DEX 路由。 已完成对接 Uniswap V2 Router02—— 使用真实链上 getAmountsOut() 报价，必须由调用方明确提供 max_slippage_bps（绝不使用默认值），没有真实报价就不会构建 calldata。构建过程中修复了一个真实 bug：模拟原本是对 intent.target（编码在 ERC-20 calldata 内部的接收方/授权对象） 执行试运行，而不是对实际被调用的合约（from_token）执行——这意味着 无论真实调用是否会回滚，对任何 EOA 接收方的 transfer/approve 模拟都会悄然 “成功”。现在 BuiltTransaction 会显式携带 to；参见 tests/test_tx_builder.py 中本可捕获该问题的回归测试。bridge 仍待处理。 已完成通过官方 OP Stack L1StandardBridge（depositETHTo/depositERC20To）向 Base 和 Optimism 执行 L1->L2 存款——其他目标链、其他桥接协议以及 L2->L1 提款仍待处理；参见 关于当前状态的说明。
3. 填充威胁情报/制裁信息源；不再随附空 集合。 制裁信息源已完成（sanctioned_addresses.json——含 103 个真实 OFAC SDN 地址，可通过 scripts/refresh_ofac_list.py 刷新）。 malicious_contracts.json / verified_contracts.json 按设计仍为空——没有 类似 OFAC 制裁名单那样可用于填充它们的单一权威信息源。
4. 将 InMemoryStorage 换成持久化后端。 已提供 SQLiteStorage；用于多副本 部署的 Postgres/Redis 后端仍待处理。 PostgresStorage 已完成——已针对真实的本地 Postgres 实例测试（tests/test_postgres_storage.py），与其他后端使用相同的 双方法 MemoryBackend 接口。如有明确需求，Redis 仍待处理。
5. 添加 MCP 服务封装。 已完成（mcp_server.py）。基于 REST API 的打包版 Python/TypeScript SDK 仍待处理。
6. 发布 OpenAPI 规范和托管演示端点。
7. 在有人于生产环境依赖此服务的 BLOCK 之前，对策略引擎和风险融合进行审查/审计——这是一个安全 工具，因此也需要接受它对其他工具所应用的同等审查。
8. 添加按 Agent 划分的能力限制（委托范围控制）。 已完成—— guardian/policy/capabilities.py，并通过可选的 capability_registry 构造参数接入 DecisionEngine.evaluate()（此前它是一个独立模块， 必须在常规流程之外自行调用——参见现在可直接通过 DecisionEngine 运行的 examples/example_capability_limits.py）。默认选择启用：不传入注册表（默认行为） 则一切保持不变；运营方可以为特定 Agent 授予范围受限的能力（允许的操作类型、允许的链、 每项操作和每日支出上限、有效期），整个过程不涉及任何私钥材料。 未获授权的 Agent 不受影响。此模块仍不会接触私钥或自行签发会话密钥—— 这仍不在范围内，因为那是风险级别截然更高的问题。真正强制执行决策（而非由 Agent 自行选择遵守）仍被有意排除在范围之外。 部分完成—— onchain/ 中的 GuardianValidator 是一个 ERC-7579 模块， 对于安装了该模块的任何 ERC-4337 智能账户，它都能让决策真正无法绕过， 同时 Guardian 永远不持有密钥。它不管理会话密钥、托管或账户创建—— 它只通过证明来限制执行——因此这是“账户抽象”中真正关键、不可或缺的一部分， 但并非全部。
9. 根据已解码的模拟结果核验声明的意图。 已完成——guardian/decision/intent_verification.py 可捕获 Agent 声明的金额与实际 传入 calldata 编码的金额存在显著差异（但仍为有限值）的情况，且 DecisionEngine.evaluate() 现在会实际调用它（此前并未调用——该模块和示例脚本虽已存在， 但真实的决策流程中没有任何地方调用它）。不过，它本身仍不是可用的防护措施： 比较原子单位需要代币的 decimals()，而目前还没有 decimals 提供方。 GUARDIAN_DECIMALS_PROVIDER=rpc（RpcTokenDecimalsProvider，参见 guardian/intelligence/token/decimals.py）解决了这个问题：它会对代币自身的 decimals() 执行真实的 eth_call，并按（链、代币）永久缓存结果，因为合约部署后该值永远不会改变。 如果保留默认值 null，那么每个模拟成功且金额有限的 approve 都会如实返回 “无法在缺少 decimals 的情况下核验” WARN，而不是误报 BLOCK 或悄然跳过——只有配置真实提供方， 才会在确有不匹配时触发实际 BLOCK。参见 examples/example_intent_verification.py 中阻止真实不匹配的检查，以及 tests/test_decision_engine.py 中的 TestIntentVerificationWithRealDecimalsProvider，了解通过真实的（模拟 RPC）decimals 查询接入完整流程的版本， 而不是手动传入 token_decimals 参数。
10. 标记偏离 Agent 自身历史模式的操作。 已完成——guardian/intelligence/anomaly/analyzer.py。 这不同于信誉（单一信任评分）和策略（运营方设置的静态限制）：它会将当前意图与 该特定 Agent 自身的记录历史进行比较——即使操作符合策略限制且 Agent 的信誉良好，也能识别 新操作类型、新链，或相较该 Agent 以往操作量而言属于统计异常值的金额。历史记录少于 5 个 数据点时，它会如实报告“历史记录不足”，而不会猜测基准值——参见 tests/test_anomaly_detection.py。
11. 置于真实的 Agent 钱包前，而不只是接受通用 API 调用方提交的意图。 MetaMask Agent Wallet 的支持已完成——skills/guardian-check/ 是一项标准 Agent Skill，Agent 可将其与 MetaMask 自带的 mm skill 一同安装；在运行任何会转移资金的 mm 命令之前，Agent 都会调用该 skill，并且只有在获得 ALLOW 后才会继续。已针对运行中的 uvicorn 实例完成端到端测试（实际测试了 ALLOW/WARN/BLOCK/配置错误，而不仅仅是断言）——参见上文“在 MetaMask Agent Wallet 前使用 Guardian”一节。目前尚无可在 MetaMask 自身流程内部运行的公开钩子； 此方案则是在 Agent 编排层运行。

---

相关项目

同一作者，将相同理念应用于其他领域：

• agent-guardrail - 面向 AI Agent 工具调用的通用策略防火墙（不专用于 区块链）。已发布到 PyPI，采用 MIT 许可证，包含 46 个测试。
• x402-attest - 采用 Ed25519 加密签名、可独立验证的 Agent 间支付策略决策 证明。早期概念验证。
• open-agent-attestation - 与供应商无关的开放规范（JWT+EdDSA），用于签署 Agent 策略 决策，任何人都可以验证。上面的 x402-attest 使用自定义格式； 这是通用版本。草案 v0.1。

---

许可证

MIT - 参见 LICENSE。