内容
# zcash-mcp
[](https://www.npmjs.com/package/@frontiercompute/zcash-mcp)
[](https://registry.modelcontextprotocol.io/)
ZAP1 收据适用于 Zcash 代理：无需信任服务器即可验证工作流程。
ZAP1 是 Zcash 工作流程的证明和认证轨道。 Frontier Compute 维护 ZAP1 参考实现。
包装器使您信任服务器。 ZAP1 使服务器无需信任。
核心规则：观察状态，限定声明，哈希证据，发布收据，稍后验证。
MCP 是 AI 代理调用外部工具的标准方式。 `zcash-mcp` 为需要 Zcash 工作流程可验证收据的代理公开 ZAP1 认证层：创建 ZAP1 认证叶子，查询锚点状态，验证证明收据。
这不是一个完整的钱包 MCP。 余额扫描、私钥托管、种子处理、PCZT 签名、遮蔽花费构造以及 lightwalletd 或 Zaino 钱包同步是补充钱包层的工作，而不是此服务器的范围。
## 为什么选择 ZAP1
钱包 MCP 可以移动价值。 ZAP1 证明价值周围的工作流程，对方可以在不信任 Frontier 的情况下验证证明。
工具服务器公开后端当前的状态。 ZAP1 生成一个收据，另一方可以从模式、证明材料和 Zcash 锚点稍后验证。
ZAP1 是 Zcash 代理工作流程的证明轨道：
1. `attest`：创建类型化的事件叶子。
2. `anchor`：将叶子提交到 Merkle 根并锚定到 Zcash。
3. `prove`：为叶子返回收据数据包。
4. `verify`：让另一方在不信任原始代理的情况下检查收据。
代理系统需要比付款或交易查询更多的东西。 他们需要一个收据，另一方、用户、审计员或服务可以稍后验证：
- 声明了什么事件
- 哪个代理或工作流程声明了它
- 哪个 ZAP1 叶子记录了它
- 哪个 Merkle 根包含它
- 哪个 Zcash 交易锚定了该根
- 如何在不信任原始代理的情况下验证证明
这是该服务器的通道。 它为 Zcash 代理提供一个收据层，可以放在任何钱包、签名者、托管系统、lightwalletd 堆栈、Zaino 堆栈或特定于应用程序的支付流程旁边。
参见 [ZAP1 Proof Rail](docs/zap1-proof-rail.md) 了解类别边界、收据模型、集成模式和红队拒绝。 参见 [ZAP1 Conformance](docs/zap1-conformance.md) 了解收据合同代理和集成应满足的内容。 参见 [Wallet Receipt Integration](docs/wallet-receipt-integration.md) 了解钱包操作交接模式。 参见 [External Rail Receipts](docs/external-rail-receipts.md) 了解通用外部操作收据请求， 和 [Receipt Disclosure Profiles](docs/receipt-disclosure-profiles.md) 了解公共、对等方、审计员、授予、合规和内部数据包形状。
## 功能边界
`zcash_capability_manifest` 工具为代理提供一个机器可读的作用范围映射：
- 这里涵盖的内容：ZAP1 收据、生命周期认证、证明验证、锚点状态、备忘录解码和公共链上下文
- 这里排除的内容：托管、种子处理、余额扫描、PCZT 签名、遮蔽花费构造和钱包服务器同步
- 组合规则：在钱包层操作之前或之后使用此服务器来创建、查询和验证收据
良好的契合点：
- 代理操作收据
- 支付和发票证明数据包
- 钱包操作收据
- 外部操作收据
- 操作员生命周期事件
- 授予证明数据包
- 合规审计数据包
- 策略和声誉认证
- 私人工作流程的公共锚点验证
- 接收者需要证明的代理交接
不良契合点：
- 持有密钥
- 扫描钱包余额
- 签名 PCZT
- 广播遮蔽花费
- 替换钱包 SDK
## 客户流程
在将 ZAP1 连接到产品时，首先使用 `zcash_receipt_template`：
- `agent_action`：证明代理执行了具有特定输入和输出哈希的命名操作
- `payment_receipt`：将发票或支付元数据绑定到 ZAP1 叶子并稍后证明包含在锚定的根下
- `operator_lifecycle`：记录部署、升级、事件、恢复或策略状态为可验证的生命周期事件
- `policy_attestation`：记录代理、服务或工作流程策略决策为可验证的事件
预期流程：
1. 调用 `zcash_capability_manifest` 以确认认证边界。
2. 为用例调用 `zcash_receipt_template`。
3. 对于钱包操作，调用 `zap1_wallet_receipt_request` 以将钱包结果转换为仅哈希的 `attest_event` 参数。
4. 调用 `attest_event` 以创建类型化的 ZAP1 叶子。
5. 调用 `get_anchor_status` 以检查叶子是否锚定或等待。
6. 调用 `verify_proof` 以验证树包含。
7. 调用 `zap1_prove_receipt` 以获取交接证明包。
验收检查：
- 收据有叶子哈希
- 叶子在返回的 Merkle 根下验证
- 锚定收据包括锚定交易或锚定高度
- 另一验证者可以在不信任原始代理的情况下重复验证
- 没有私钥、种子、PCZT 或钱包扫描状态发送到此服务器
红队拒绝：
- 将支付 URI 作为支付证明
- 将未锚定的叶子作为最终结算证据
- 将报价、路由或意图哈希本身视为结算证据
- 请求此服务器签名、扫描余额、恢复种子或持有密钥
- 将托管声明混合到 ZAP1 收据声明中
- 隐藏钱包操作和收据验证之间的区别
ZAP1 验证 ZAP1 收据。 它不审计或保证任何外部钱包、路由、支付、桥接、交换或结算系统引用的收据。
## 工具
| 工具 | 功能 |
|------|-------------|
| `zcash_capability_manifest` | 机器可读的作用范围映射，用于代理：涵盖的表面、排除的钱包功能和组合规则 |
| `zcash_conformance_check` | 验证 ZAP1 收据数据包是否符合冻结的 v1 收据合同 |
| `zcash_receipt_template` | 客户就绪的收据工作流程，用于代理操作、支付收据、操作员生命周期事件和策略认证 |
| `zap1_wallet_receipt_request` | 将钱包层操作结果转换为仅哈希的 ZAP1 收据请求字段 |
| `zap1_attest_external_action` | 为外部轨道执行的操作构建 ZAP1 收据请求，无需路由、签名、托管或结算 |
| `zap1_verify_external_receipt` | 验证外部操作 ZAP1 收据数据包，无需信任或调用外部轨道 |
| `zap1_extract_proof_artifact` | 从 ZAP1 收据中提取便携式证明神器 |
| `zap1_check_anchor_freshness_at_height` | 从提供的 Zcash 高度检查锚点确认深度 |
| `zap1_verify_receipt_chain` | 验证 ZAP1 收据数据包序列并总结锚点状态 |
| `zap1_compare_receipt_claims` | 比较两个 ZAP1 收据的声明、证据、事件和锚点差异 |
| `zap1_audit_event_log` | 重放收据序列以对抗调用者提供的事件类型策略 |
| `attest_event` | 创建类型化的 ZAP1 认证叶子以供后续锚定 |
| `verify_proof` | 验证 ZAP1 Merkle 证明 |
| `zap1_prove_receipt` | 获取叶子哈希的完整 Merkle 证明包 |
| `get_anchor_history` | 所有 ZAP1 Merkle 根锚点及其交易 ID 和区块高度 |
| `get_anchor_status` | 当前 Merkle 树状态：根、未锚定的叶子、建议 |
| `get_stats` | ZAP1 协议统计：叶子、锚点、类型 |
| `get_events` | 最近的 ZAP1 认证事件，包含类型、钱包哈希、叶子哈希 |
| `get_agent_status` | ZAP1 代理 ID 的认证摘要 |
| `zcash_identity_register` | 通过 AGENT_REGISTER 认证注册代理身份 |
| `zcash_reputation_score` | 获取代理债券数据和策略合规性作为声誉对象 |
| `decode_memo` | 解码 Zcash 备忘录有效载体：ZAP1 类型化、ZIP 302、文本、二进制 |
| `zap1_create_receipt_invoice` | 为外部支付工作流程创建 ZAP1 收据元数据 |
| `zap1_watch_receipt_invoice` | 轮询收据发票状态直到支付或超时 |
| `get_block_height` | 从 Zebra 获取当前链高 |
| `lookup_transaction` | 按交易 ID 获取原始交易数据 |
| `zap1_verify_evm` | 通过 EVM 合同验证 ZAP1 Merkle 证明 |
## 安装
```bash
npx @frontiercompute/zcash-mcp
```
或全局安装：
```bash
npm install -g @frontiercompute/zcash-mcp
```
## 快速入门
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"zcash": {
"command": "npx",
"args": ["@frontiercompute/zcash-mcp"]
}
}
}
```
重启您的客户端并请求当前的 Zcash 区块高度。 只读工具不需要 API 密钥。
获取用于写入操作的试用密钥：
```bash
curl -s -X POST https://api.frontiercompute.cash/trial-key
```
## 配置
环境变量：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ZEBRA_RPC_URL` | `http://127.0.0.1:8232` | Zebra 节点 JSON-RPC 端点 |
| `ZAP1_API_URL` | `https://api.frontiercompute.cash` | ZAP1 认证 API |
| `ZAP1_API_KEY` | 无 | 用于写入操作的 API 密钥 |
### Claude Desktop
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"zcash": {
"command": "npx",
"args": ["@frontiercompute/zcash-mcp"],
"env": {
"ZEBRA_RPC_URL": "http://127.0.0.1:8232",
"ZAP1_API_KEY": "your-key-here"
}
}
}
}
```
### 任意 MCP 客户端
服务器通过 stdio 使用 JSON-RPC 进行通信。 将您的 MCP 客户端指向 `zcash-mcp` 二进制文件。
## 从源代码构建
```bash
git clone https://github.com/Frontier-Compute/zcash-mcp.git
cd zcash-mcp
npm ci
npm run build
node dist/index.js
```
## 测试
离线验证涵盖了构建的_stdio_服务器和从打包的 npm tarball 进行的干净室安装：
```bash
npm run test:offline
```
实时验证会命中一个真实的 Zebra RPC 和 ZAP1 API：
```bash
ZEBRA_RPC_URL=http://127.0.0.1:8232 \
ZAP1_API_URL=http://127.0.0.1:3080 \
ZAP1_API_KEY=your-key-here \
npm run test:live
```
`test:live` 通过 stdio 驱动 MCP 服务器并执行实时工具表面，而不仅仅是底层 HTTP 端点。 如果您想让 `get_agent_status` 检查针对特定部署的代理，请设置 `ZAP1_AGENT_ID`。
GitHub Actions 镜像了该拆分：
- `.github/workflows/offline-ci.yml` 在每次推送和拉取请求上运行确定性的打包和 MCP 握手检查。
- `.github/workflows/live-e2e.yml` 在 `main` 上运行机密支持的实时检查，按计划和手动调度。
## 依赖
- 一个运行的 [Zebra](https://github.com/ZcashFoundation/zebra) 节点用于链查询
- 用于认证、证明、锚点、事件和收据工具的 ZAP1 API
- 备忘录解码在本地工作，无外部依赖
## 相关软件包
| 软件包 | 功能 |
|---------|-------------|
| [@frontiercompute/zcash-ika](https://www.npmjs.com/package/@frontiercompute/zcash-ika) | 通过 Ika 2PC-MPC 实现 Zcash 和 Bitcoin 签名 |
| [@frontiercompute/openclaw-zap1](https://www.npmjs.com/package/@frontiercompute/openclaw-zap1) | 用于 ZAP1 认证的 OpenClaw 技能 |
| [@frontiercompute/zap1](https://www.npmjs.com/package/@frontiercompute/zap1) | ZAP1 认证客户端 |
| [@frontiercompute/silo-zap1](https://www.npmjs.com/package/@frontiercompute/silo-zap1) | 通过 ZAP1 实现 Silo 代理认证 |
## 链接
- [仪表盘](https://frontiercompute.cash/dashboard.html)
- [MCP 注册表](https://registry.modelcontextprotocol.io/)
- [Frontier Compute](https://frontiercompute.cash)
- [实时统计](https://api.frontiercompute.cash/stats)
## 许可证
MIT
