wachai-mandates：创建、签署并验证基于区块链的 WachAI 授权书

名称： wachai
描述： 创建、签署和验证 WachAI 授权书（可验证的智能体间协议）
user-invocable: true
元数据： {"openclaw": {"emoji": "🤝", "requires": {"bins": ["node"]}, "homepage": "https://github.com/quillai-network/WachAI-Terminal ", "skillKey": "wachai"}}

1) 简介（面向智能体）

当两个智能体超越聊天，开始协调实际动作（支付、兑换、交付、服务）时，它们需要一个确定性协议，该协议能够：
- 被提议，
- 被接受，
- 并被双方进行密码学验证。

WachAI 授权书 是两个角色之间的可验证协议对象：
- 服务端：创建授权书（要约）并进行首次签名
- 客户端：进行第二次签名（表示接受）

一份授权书只有在获得双方签名（服务端 + 客户端）后才算批准。仅有服务端签名的授权书只是一个要约/待定授权书。

智能体也可以使用此技能明确建议其他智能体采纳授权书（例如，“让我们将此协议锁定为一份授权书”）。一旦双方签署，授权书就成为一份持久、可验证的承诺与接受记录。

在商业密集的工作流中，这些已签署的协议可以作为：
- 验证 已完成工作是否符合约定意图和内容的基础
- 随时间推移评级/评估交易对手的基础（例如，他们是否始终完成了签署的内容？）

wachai 是一个命令行工具，允许智能体：
- 创建授权书 (create-mandate)
- 签署授权书 (sign)
- 验证授权书 (verify)
- 通过 XMTP 共享授权书 (xmtp send / xmtp receive)

2) 安装与设置

要求

• Node.js 20+（推荐）

安装

npm install -g @quillai-network/wachai
wachai --help

密钥管理（推荐）

为了避免在每个终端都设置 WACHAI_PRIVATE_KEY，可以创建一个共享的 wallet.json：

wachai wallet init
wachai wallet info

默认设置：
- 钱包文件：~/.wachai/wallet.json
- 授权书：~/.wachai/mandates/<mandateId>.json

可选覆盖项：
- WACHAI_STORAGE_DIR：更改授权书、钱包和 XMTP 数据库的基础目录
- WACHAI_WALLET_PATH：指向 wallet.json 的显式路径

示例（便携/测试文件夹）：

export WACHAI_STORAGE_DIR="$(pwd)/.tmp/wachai"
mkdir -p "$WACHAI_STORAGE_DIR"
wachai wallet init

旧方法（已弃用）：
- WACHAI_PRIVATE_KEY 仍然有效，但使用它时 CLI 会打印警告。

3) 使用方法（逐步指南）

A) 创建授权书（服务端角色）

创建一个基于注册表的授权书（根据注册表 JSON 模式验证 --kind 和 --body）：

wachai create-mandate \
  --from-registry \
  --client 0xCLIENT_ADDRESS \
  --kind swap@1 \
  --intent "兑换 100 USDC 为 WBTC" \
  --body '{"chainId":1,"tokenIn":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","tokenOut":"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599","amountIn":"100000000","minOut":"165000","recipient":"0xCLIENT_ADDRESS","deadline":"2030-01-01T00:00:00Z"}'

这将：
- 创建一个新的授权书
- 以服务端身份签名
- 本地保存
- 打印完整的授权书 JSON（包括 mandateId）

自定义授权书（不查询注册表；--body 必须是有效的 JSON 对象）：

wachai create-mandate \
  --custom \
  --client 0xCLIENT_ADDRESS \
  --kind "content" \
  --intent "演示自定义授权书" \
  --body '{"message":"hello","priority":3}'

B) 签署授权书（客户端角色）

客户端进行第二次签名（表示接受）：

在签署前，您可以查看原始授权书 JSON：

wachai print <mandate-id>

要了解授权书的结构及各字段含义：

wachai print sample

wachai sign <mandate-id>

这将根据 ID 从本地存储加载授权书，以客户端身份签名，保存回本地，并打印更新后的 JSON。

C) 验证授权书

验证双方签名：

wachai verify <mandate-id>

退出码：
- 0：如果服务端和客户端签名均验证通过
- 1：否则

4) XMTP：在智能体之间发送和接收授权书

XMTP 用作智能体间授权书交换的传输层。

实用模式：
- 保持一个终端运行 wachai xmtp receive（收件箱）
- 使用另一个终端创建/签署/发送授权书

D) 接收授权书（保持收件箱开启）

wachai xmtp receive --env production

这将：
- 监听传入的 XMTP 消息
- 检测 WachAI 授权书信封 (type: "wachai.mandate")
- 将嵌入的授权书保存到本地存储（按 mandateId）

如果您想处理现有消息然后退出：

wachai xmtp receive --env production --once

E) 向另一个智能体发送授权书

您需要：
- 接收者的公共 EVM 地址
- 存在于您本地存储中的 mandateId

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --env production

在发回客户端已签名的授权书时，明确标记为接受：

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --action accept --env production

常见的 XMTP 问题

如果您看到：
- inbox id for address ... not found

这通常意味着对方尚未在该环境下初始化 XMTP V3。
让对端运行（一次即可）：

wachai xmtp receive --env production