zcash-mcp

zcash-mcp

为 Zcash Agent 提供 ZAP1 收据：无需信任服务端，即可验证工作流。

ZAP1 是 Zcash 工作流的证明与证明轨道。Frontier Compute 维护 ZAP1 参考实现。

使用封装器意味着你必须信任服务端。ZAP1 则让你无需信任服务端。

核心规则：观察状态、限定声明范围、对证据进行哈希处理、签发收据，并在之后验证。

MCP 是 AI Agent 调用外部工具的标准方式。zcash-mcp 为需要围绕 Zcash 工作流获取可验证收据的 Agent 提供 ZAP1 证明层：创建 ZAP1 证明叶、查询锚定状态，并验证证明收据。

这不是完整的钱包 MCP。余额扫描、私钥保管、助记词处理、PCZT 签名、屏蔽支付构建，以及 lightwalletd 或 Zaino 钱包同步，都属于互补的钱包层工作，不在此服务的范围内。

为什么选择 ZAP1

钱包 MCP 可以转移价值。ZAP1 证明价值相关的工作流，对手方无需信任 Frontier 即可验证证明。

工具服务会公开后端当前声称的内容。ZAP1 则会生成一份收据，其他方之后可根据模式、证明材料和 Zcash 锚点进行验证。

ZAP1 是 Zcash Agent 工作流的证明轨道：

1. attest：创建带类型的事件叶。
2. anchor：将叶提交到锚定于 Zcash 的 Merkle 根。
3. prove：返回某个叶的收据数据包。
4. verify：让其他方检查收据，而无需信任原始 Agent。

Agent 系统需要的不只是付款或交易查询。它们还需要一份其他 Agent、用户、审计员或服务之后能够验证的收据：

• 声明了什么事件
• 由哪个 Agent 或工作流作出声明
• 哪个 ZAP1 叶记录了该事件
• 哪个 Merkle 根包含该叶
• 哪笔 Zcash 交易锚定了该根
• 如何在不信任原始 Agent 的情况下验证证明

这正是此服务的定位。它为 Zcash Agent 提供收据层，可与任何钱包、签名器、托管系统、lightwalletd 技术栈、Zaino 技术栈或特定于应用的支付流程并行使用。

请参阅 ZAP1 Proof Rail，了解类别边界、收据模型、集成模式和红队拒绝规则。请参阅 ZAP1 Conformance，了解 Agent 和集成应满足的收据契约。请参阅 Wallet Receipt Integration，了解钱包操作交接模式。请参阅 External Rail Receipts，了解通用外部操作收据请求；另请参阅 Receipt Disclosure Profiles，了解公开、对手方、审计员、资助、合规和内部数据包格式。

能力边界

zcash_capability_manifest 工具为 Agent 提供机器可读的范围图：

• 此处涵盖：ZAP1 收据、生命周期证明、证明验证、锚定状态、备忘录解码和公开链上下文
• 此处不涵盖：托管、种子处理、余额扫描、PCZT 签名、屏蔽支付构建和钱包服务端同步
• 组合规则：在钱包层操作之前或之后使用此服务，以创建、查询和验证收据

适用场景：

• Agent 操作收据
• 支付和发票证明包
• 钱包操作收据
• 外部操作收据
• 操作员生命周期事件
• 授权证明包
• 合规审计包
• 策略和声誉证明
• 私密工作流的公开锚定验证
• 跨 Agent 交接，接收方需要的是证明，而非托管

不适用场景：

• 持有密钥
• 扫描钱包余额
• 签署 PCZT
• 广播屏蔽支付
• 替代钱包 SDK

客户流程

将 ZAP1 接入产品时，先使用 zcash_receipt_template。它会针对所需的收据类型返回一套可直接提供给客户的工作流：

• agent_action：证明 Agent 使用特定输入和输出哈希执行了指定操作
• payment_receipt：将发票或支付元数据关联到 ZAP1 叶子，并在之后证明其包含在锚定根下
• operator_lifecycle：将部署、升级、事故、恢复或策略状态记录为可验证的生命周期事件
• policy_attestation：将 Agent、服务或工作流的策略决策记录为可验证事件

预期流程：

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 根验证叶子
• v2 收据保留每个兄弟节点位置和已承诺的 leaf_count
• 锚定最终性来自经过单独验证的根开启证明材料，而不能仅凭 txid、高度或状态元数据判定
• 其他验证者无需信任原始 Agent，即可重复验证
• 未向此服务发送私钥、种子、PCZT 或钱包扫描状态

红队拒绝项：

• 将支付 URI 视为支付证明
• 将未锚定的叶子视为最终结算证据
• 将报价、路线或意图哈希本身视为结算证据
• 要求此服务签名、扫描余额、恢复种子或持有密钥
• 将托管声明混入 ZAP1 收据声明
• 混淆钱包操作与收据验证之间的区别

ZAP1 用于验证 ZAP1 收据。它不会审计或保证收据中引用的任何外部钱包、路线、支付、桥接、交易所或结算系统。

工具

工具	功能
zcash_capability_manifest	供 Agent 使用的机器可读范围映射：覆盖的领域、排除的钱包功能和组合规则
zcash_conformance_check	仅验证冻结版 v1 回执数据包的结构；v1 无法证明已纳入或锚定已确认
zcash_receipt_template	面向客户的回执工作流，适用于 Agent 操作、付款回执、操作员生命周期事件和策略证明
zap1_wallet_receipt_request	将钱包层操作结果转换为仅含哈希的 ZAP1 回执请求字段
zap1_attest_external_action	将有限范围的外部验证证据映射到受支持的 ZAP1 AGENT_ACTION 写入约定，并预先计算预期的类型化叶子
zap1_verify_external_receipt	验证旧版 v1 外部回执的结构，但不声称其具备加密包含证明或锚定确认
zap1_verify_receipt_v2	验证官方 proof-bundle-v2 与保留的 AGENT_ACTION 见证，或 integration receipt-v2；锚定确认仍需单独验证
zap1_extract_proof_artifact	从 ZAP1 回执中提取可移植的证明文件
zap1_check_anchor_freshness_at_height	根据提供的区块高度计算深度，不声称链上已确认
zap1_verify_receipt_chain	验证旧版 v1 回执序列的结构，但不声称证明或锚定有效
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 根锚定记录及其 txid 和区块高度
get_anchor_status	当前 Merkle 树状态：根、未锚定叶子、建议
get_stats	ZAP1 协议统计信息：叶子、锚定记录、类型
get_events	获取近期 ZAP1 证明事件及其类型、钱包哈希和叶子哈希
get_agent_status	获取 ZAP1 Agent ID 的证明摘要
zcash_identity_register	通过 AGENT_REGISTER 证明注册 Agent 身份
zcash_reputation_score	获取 Agent 保证金数据和策略合规情况，并生成信誉对象
decode_memo	解码 Zcash 备注内容：ZAP1 类型化数据、ZIP 302、文本、二进制
zap1_create_receipt_invoice	为外部付款工作流创建 ZAP1 回执元数据
zap1_watch_receipt_invoice	轮询回执发票状态，直到付款完成或超时
get_block_height	从 Zebra 获取当前链高度
lookup_transaction	根据 txid 获取原始交易数据
zap1_verify_evm	通过 EVM 合约在链上验证 ZAP1 Merkle 证明

安装

npx @frontiercompute/zcash-mcp

或全局安装：

npm install -g @frontiercompute/zcash-mcp

快速入门

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "zcash": {
      "command": "npx",
      "args": ["@frontiercompute/zcash-mcp"]
    }
  }
}

重启客户端，并查询当前 Zcash 区块高度。只读工具 无需 API 密钥。

获取用于写入操作的试用密钥：

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：

{
  "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 二进制文件。

从源代码构建

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 进行的纯净环境安装：

npm run test:offline

在线验证会调用真实的 Zebra RPC 和 ZAP1 API：

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 检查针对特定的已部署 Agent，请设置 ZAP1_AGENT_ID。

GitHub Actions 也采用相同的划分：

• .github/workflows/offline-ci.yml 会在每次推送和拉取请求时运行确定性的打包和 MCP 握手检查。
• .github/workflows/live-e2e.yml 会在 main 上、按计划以及通过手动触发运行需要密钥的在线检查。

依赖项

• 用于查询链数据的运行中 Zebra 节点
• 用于证明、存证、锚定、事件和收据工具的 ZAP1 API
• Memo 解码可在本地运行，无需外部依赖

相关软件包

软件包	功能
@frontiercompute/zcash-ika	通过 Ika 2PC-MPC 对 Zcash 和 Bitcoin 进行签名
@frontiercompute/openclaw-zap1	用于 ZAP1 证明的 OpenClaw 技能
@frontiercompute/zap1	ZAP1 证明客户端
@frontiercompute/silo-zap1	通过 ZAP1 对 Silo Agent 进行证明

链接

• 仪表板
• MCP 注册表
• Frontier Compute
• 实时统计

许可证

MIT