Back to Details

zk-proofs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zero-Knowledge Proofs & Privacy

零知识证明与隐私

Privacy patterns and ZK verification on Stellar/Soroban. Capability is protocol- and SDK-version dependent — always verify CAP status, network version, and 
soroban-sdk
host-function support before relying on a primitive.
Stellar/Soroban 上的隐私模式与 ZK 验证。功能依赖于协议和 SDK 版本——在使用任何原语之前，请务必确认 CAP 状态、网络版本以及 
soroban-sdk
宿主函数的支持情况。

When to use this skill

何时使用此技能

  • Implementing a Groth16 (or other SNARK) verifier as a Soroban contract
  • Using BLS12-381 host functions
  • Planning for BN254 / Poseidon (currently proposed via CAP-0074/0075)
  • Integrating Noir or RISC Zero proofs
  • Building privacy pools, confidential tokens, or Merkle-tree-backed commitments
  • 将 Groth16（或其他 SNARK）验证器实现为 Soroban 合约
  • 使用 BLS12-381 宿主函数
  • 规划 BN254 / Poseidon 的使用（目前通过 CAP-0074/0075 提出）
  • 集成 Noir 或 RISC Zero 证明
  • 构建隐私池、保密代币或基于 Merkle 树的承诺

Status-sensitive — always verify

状态敏感——务必确认

  1. CAP status (
    Accepted
    /
    Implemented
    vs draft)
  2. Target network software + protocol version
  3. soroban-sdk
    release support for the target host functions
  4. Available feature flags + graceful fallback paths
  1. CAP 状态（
    已接受
    /
    已实现
    与草案的区别）
  2. 目标网络软件 + 协议版本
  3. soroban-sdk
    版本对目标宿主函数的支持情况
  4. 可用的功能标志 + 优雅的回退路径

Related skills

相关技能

  • Soroban verifier contract patterns + tests → 
    ../soroban/SKILL.md
  • Confidential-token integration with classic assets → 
    ../assets/SKILL.md
  • Off-chain proof verification UI → 
    ../dapp/SKILL.md
  • CAPs referenced here → 
    ../standards/SKILL.md
  • Soroban 验证器合约模式 + 测试 → 
    ../soroban/SKILL.md
  • 保密代币与经典资产的集成 → 
    ../assets/SKILL.md
  • 链下证明验证 UI → 
    ../dapp/SKILL.md
  • 此处引用的 CAP → 
    ../standards/SKILL.md

When to use this guide

何时使用本指南

Use this guide when the user asks for:
  • On-chain ZK proof verification patterns
  • Privacy-preserving smart contract architecture
  • BN254/Poseidon readiness planning
  • Groth16 or PLONK integration strategy
  • Cross-chain proof verification design
This guide is intentionally status-aware. ZK capabilities on Stellar evolve with protocol and SDK releases.
当用户询问以下内容时使用本指南：
  • 链上 ZK 证明验证模式
  • 隐私保护型智能合约架构
  • BN254/Poseidon 就绪规划
  • Groth16 或 PLONK 集成策略
  • 跨链证明验证设计
本指南特意关注状态变化。Stellar 上的 ZK 功能会随协议和 SDK 版本更新而演进。

Source-of-truth checks (required)

权威来源检查（必填）

Before implementation, always verify:
  1. CAP status in 
    stellar/stellar-protocol
    (
    Accepted
    /
    Implemented
    vs draft/awaiting decision)
  2. Target network protocol/software version
  3. soroban-sdk
    support for required cryptographic host functions
  4. Availability of production examples matching your proving system
Primary references:
在实施前，请务必验证：
  1. stellar/stellar-protocol
    中的 CAP 状态（
    已接受
    /
    已实现
    与草案/待决策的区别）
  2. 目标网络的协议/软件版本
  3. soroban-sdk
    对所需加密宿主函数的支持情况
  4. 是否存在与你的证明系统匹配的生产示例
主要参考资料：

Capability model

能力模型

Treat advanced cryptography as capability-gated:
  • Capability A: proof verification primitive support
  • Capability B: hash primitive support
  • Capability C: SDK ergonomics and bindings
  • Capability D: operational cost envelope
Do not assume all capabilities are present on all networks/environments.
将高级密码学视为能力 gated：
  • 能力 A：证明验证原语支持
  • 能力 B：哈希原语支持
  • 能力 C：SDK 易用性与绑定
  • 能力 D：运营成本范围
不要假设所有能力在所有网络/环境中都可用。

Architecture patterns

架构模式

1) Verification gateway

1) 验证网关

Use a dedicated verifier contract (or module) for cryptographic checks:
  • Normalize and validate inputs
  • Enforce domain separation for statements
  • Verify proof
  • Emit explicit success/failure events
Benefits:
  • Smaller audit surface
  • Easier upgrades/migrations
  • Cleaner operational telemetry
使用专用的验证器合约（或模块）进行加密检查：
  • 标准化并验证输入
  • 强制声明的域分离
  • 验证证明
  • 发出明确的成功/失败事件
优势：
  • 更小的审计范围
  • 更易升级/迁移
  • 更清晰的运营遥测

2) Policy-and-proof split

2) 策略与证明分离

Separate concerns:
  • Verifier
    : cryptographic validity only
  • Policy
    : business/risk/compliance logic
  • Application
    : state transition after verifier + policy pass
Benefits:
  • Better testability
  • Safer upgrades
  • Clearer incident response
分离关注点：
  • 验证器
    ：仅负责加密有效性
  • 策略
    ：业务/风险/合规逻辑
  • 应用
    ：验证器 + 策略通过后的状态转换
优势：
  • 更好的可测试性
  • 更安全的升级
  • 更清晰的事件响应

3) Feature flags and graceful fallback

3) 功能标志与优雅回退

Gate advanced paths by environment support:
  • Enable ZK flows only where required primitives are verified available
  • Keep deterministic fallback behavior for unsupported environments
  • Document supported network/protocol matrix in deployment notes
根据环境支持限制高级路径：
  • 仅在确认所需原语可用时启用 ZK 流程
  • 为不支持的环境保留确定性回退行为
  • 在部署说明中记录支持的网络/协议矩阵

Integration checklist

集成检查清单

  • Target network supports required primitives
  • SDK pin supports required APIs
  • Proof statement includes anti-replay binding (nonce/context)
  • Full simulation path is covered (proof + policy + state transition)
  • Negative-path tests exist for malformed/tampered inputs
  • Resource budget checks are documented for realistic proof sizes
  • Security review documents all cryptographic assumptions
  • 目标网络支持所需原语
  • 固定的 SDK 版本支持所需 API
  • 证明声明包含防重放绑定（随机数/上下文）
  • 覆盖完整的模拟路径（证明 + 策略 + 状态转换）
  • 存在针对格式错误/篡改输入的负面路径测试
  • 记录真实证明大小下的资源预算检查
  • 安全评审记录所有加密假设

Common pitfalls

常见陷阱

Over-trusting proof payload shape

过度信任证明负载格式

A payload that parses is not equivalent to a valid statement for your application.
Mitigation:
  • Validate public-input semantics and statement domain explicitly.
能解析的负载并不等同于你的应用所需的有效声明。
缓解措施：
  • 显式验证公共输入语义和声明域。

Missing anti-replay controls

缺少防重放控制

Valid proofs can be replayed without context binding.
Mitigation:
  • Bind proofs to session/nonce/action scope and persist replay guards.
有效的证明在没有上下文绑定的情况下可能被重放。
缓解措施：
  • 将证明绑定到会话/随机数/操作范围，并持久化重放防护机制。

Monolithic contract design

单体合约设计

Combining verifier, policy, and state logic increases audit complexity.
Mitigation:
  • Keep verifier logic isolated and narrow.
将验证器、策略和状态逻辑组合在一起会增加审计复杂度。
缓解措施：
  • 保持验证器逻辑独立且范围狭窄。

Hardcoded protocol assumptions

硬编码协议假设

Assuming primitive availability across all networks causes runtime failures.
Mitigation:
  • Capability-gate and verify at deployment time.
假设原语在所有网络中都可用会导致运行时失败。
缓解措施：
  • 采用能力 gated，并在部署时验证。

Testing strategy

测试策略

Unit tests

单元测试

  • Input domain validation
  • Replay protection behavior
  • Event correctness
  • 输入域验证
  • 防重放保护行为
  • 事件正确性

Integration tests

集成测试

  • End-to-end proof submission flow
  • Negative cases: tampered input, stale nonce, unsupported feature path
  • Network-configuration differences (local/testnet/mainnet)
  • 端到端证明提交流程
  • 负面案例：篡改的输入、过期的随机数、不支持的功能路径
  • 网络配置差异（本地/测试网/主网）

Operational tests

运营测试

  • Cost/resource envelope under realistic proof sizes
  • Load behavior on verifier hot paths
  • Upgrade/migration safety tests for verifier changes
  • 真实证明大小下的成本/资源范围
  • 验证器热点路径的负载行为
  • 验证器变更的升级/迁移安全测试

Security review focus

安全评审重点

  • Authorization and anti-replay guarantees
  • Statement domain separation
  • Upgrade controls around verifier/policy modules
  • Denial-of-service resistance and bounded workloads
  • Event/log coverage for forensic traceability
  • 授权与防重放保证
  • 声明域分离
  • 验证器/策略模块的升级控制
  • 抗拒绝服务能力与有限工作负载
  • 用于法医可追溯性的事件/日志覆盖

Example starting points

示例起点

What not to do

禁止操作

  • Do not claim specific primitives are production-ready without checking CAP status and network support.
  • Do not hardcode draft-spec behavior as guaranteed runtime behavior.
  • Do not skip simulation and negative-path testing for verifier flows.
  • 在未检查 CAP 状态和网络支持的情况下，不要声称特定原语已准备好投入生产。
  • 不要将草案规范的行为硬编码为有保证的运行时行为。
  • 不要跳过验证器流程的模拟和负面路径测试。