安全架构

概述

AgentWallex 基于一个核心原则：AI Agent 永远不应该接触私钥。交易通过多方计算（MPC）签名，任何一方都无法持有完整密钥。

四层安全防护

第一层：身份认证

每个 API 请求都通过双令牌系统认证：

• API Key（awx_...）— 长期有效，标识你的账户。请安全存储在环境变量中。
• Session Token — 短期有效，限定特定 Agent 和操作范围。自动轮换。

// API 密钥认证你的账户
const aw = new AgentWallex({ apiKey: process.env.AGENTWALLEX_API_KEY! });
 
// Session Token 由 SDK 内部管理
// 每个 Agent 获得独立的限定范围会话

关键属性：

• API 密钥可无停机轮换
• Session Token 自动过期（可配置：1-24 小时）
• 按 Agent 独立的权限范围
• 成长版和企业版支持 IP 白名单

第二层：策略引擎

每笔交易在签名前必须通过策略引擎。策略按顺序评估 — 首个违规即终止交易。

await aw.policies.update("agent_abc123", {
  // 支出限额
  maxTransactionAmount: "500",      // 单笔交易上限
  dailyLimit: "5000",               // 滚动 24 小时限额
 
  // 地址控制
  allowedAddresses: ["0x..."],      // 白名单（设置后仅允许这些地址）
  blockedAddresses: ["0x..."],      // 黑名单
 
  // 代币控制
  allowedTokens: ["USDC", "USDT"], // 限制代币类型
 
  // 速率控制
  velocityLimit: {
    maxCount: 100,                  // 最大交易次数
    windowSeconds: 3600,            // 每小时
  },
 
  // 人工审批
  requireHumanApproval: true,       // 大额交易
  humanApprovalThreshold: "1000",   // 触发审批的金额
});

第三层：MPC 签名（Paratro）

AgentWallex 使用 Paratro 的 2-of-3 门限 MPC 协议：

• 分片 1 — 由 AgentWallex 签名服务持有
• 分片 2 — 由独立托管节点持有
• 分片 3 — 存储在冷钱包中用于恢复

关键安全属性：

• 完整私钥从不在内存中重组
• 任意 2/3 分片即可签名交易
• 单个分片被攻破不会危及钱包
• 密钥生成使用分布式密钥生成（DKG）— 任何一方都无法看到完整密钥

第四层：人机协同

对于大额或异常交易，AgentWallex 可路由至人工审批：

• 超过可配置阈值的交易
• 发往新（未见过的）地址的交易
• 异常监控检测到的异常模式

{
  "event": "approval.requested",
  "data": {
    "transactionId": "tx_pending_123",
    "agentId": "agent_abc123",
    "amount": "2500.00",
    "reason": "金额超过人工审批阈值 (1000)",
    "expiresAt": "2025-01-15T11:00:00Z"
  }
}

审批可通过控制面板、API 或 Webhook 集成处理。

双层策略架构

AgentWallex 在两个独立层级执行策略：

业务层（开发者配置）

你的自定义规则 — 支出限额、白名单、速率控制。通过 API 或控制面板设置，可随时更新。

基础设施安全网（Paratro 强制执行）

在 MPC 签名层面强制执行的硬限制，无法通过 API 调用覆盖：

即使你的 API 密钥被泄露，基础设施安全网也能防止灾难性损失。

密钥管理生命周期

密钥生成

密钥使用分布式密钥生成（DKG）生成。在任何时刻，任何一方都看不到完整私钥：

1. 3 个 MPC 节点各自生成随机份额
2. 份额通过密码学组合生成公钥
3. 对应的私钥仅以分布式分片形式存在

密钥轮换

密钥分片定期轮换而不更改钱包地址。这称为"主动秘密共享" — 旧分片在轮换后变得无效。

紧急冻结

任何授权方都可以即时冻结钱包：

// 通过 SDK
await aw.agents.freeze("agent_abc123");
 
// 通过控制面板 — 一键冻结
// 通过 API — PUT /agents/:id/status

被冻结的钱包无法签署任何交易，直到明确解冻（需经过强制冷却期）。

审计日志

所有操作都被不可篡改地记录：

• 所有 API 请求（包含 IP、User Agent、时间戳）
• 所有策略评估（通过/失败及原因）
• 所有签名操作
• 所有冻结/解冻事件
• 所有 Webhook 投递

日志保留 90 天（入门版）、1 年（成长版）或自定义（企业版）。