zk-proofs

---
name: zk-proofs
description: 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.
user-invocable: true
argument-hint: "[zk task]"
---

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

## 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:
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:
- [CAP-0059](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0059.md) (BLS12-381)
- [CAP-0074](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0074.md) (BN254 proposal)
- [CAP-0075](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0075.md) (Poseidon/Poseidon2 proposal)
- [Stellar protocol/software versions](https://developers.stellar.org/docs/networks/software-versions)
- [RPC providers](https://developers.stellar.org/docs/data/apis/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](https://github.com/stellar/soroban-examples)
- [Groth16 verifier example](https://github.com/stellar/soroban-examples/tree/main/groth16_verifier)
- [Security guide](../soroban/SKILL.md)
- [Advanced patterns](../soroban/SKILL.md)
- [Standards reference](../standards/SKILL.md)

## 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.