zk-proofs

Original：🇺🇸 English

Translated

Zero-knowledge cryptography and privacy patterns on Stellar/Soroban. Covers Groth16 verification, BLS12-381 (CAP-0059, available), BN254 + Poseidon host functions (CAP-0074/0075, status-sensitive), Noir / RISC Zero integration, privacy pools, confidential tokens, Merkle tree commitments, and status-sensitive guidance for protocol/SDK readiness. Use when building privacy-preserving applications or ZK-verifier contracts on Stellar.

20installs

Sourcestellar/stellar-dev-skill

Added on2026-06-08

NPX Install

npx skill4agent add stellar/stellar-dev-skill zk-proofs

SKILL.md Content

View Translation Comparison →

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.

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

Status-sensitive — always verify

CAP status (
```
Accepted
```
/
```
Implemented
```
vs draft)
Target network software + protocol version
```
soroban-sdk
```
release support for the target host functions
Available feature flags + graceful fallback paths

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
```

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.

Source-of-truth checks (required)

Before implementation, always verify:

CAP status in

stellar/stellar-protocol

(

Accepted

/

Implemented

vs draft/awaiting decision)

Target network protocol/software version
```
soroban-sdk
```
support for required cryptographic host functions
Availability of production examples matching your proving system

Primary references:

CAP-0059 (BLS12-381)
CAP-0074 (BN254 proposal)
CAP-0075 (Poseidon/Poseidon2 proposal)
Stellar protocol/software versions
RPC providers

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.

Architecture patterns

1) Verification gateway

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

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

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

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

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.

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

Soroban examples
Groth16 verifier example
Security guide
Advanced patterns
Standards reference

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.

zk-proofs

NPX Install

Tags

SKILL.md Content

Zero-Knowledge Proofs & Privacy

When to use this skill

Status-sensitive — always verify

Related skills

When to use this guide

Source-of-truth checks (required)

Capability model

Architecture patterns

1) Verification gateway

2) Policy-and-proof split

3) Feature flags and graceful fallback

Integration checklist

Common pitfalls

Over-trusting proof payload shape

Missing anti-replay controls

Monolithic contract design

Hardcoded protocol assumptions

Testing strategy

Unit tests

Integration tests

Operational tests

Security review focus

Example starting points

What not to do