Starknet Privacy

Privacy pool protocol for Starknet.

Users submit private transfers through the SDK, which compiles client actions and sends them to an operator-side proving service. The proving service executes these actions in virtual Starknet blocks and returns a validity proof together with proof facts back to the SDK. The SDK builds a transaction that the wallet submits (ideally via a paymaster to avoid leaking sender info) to Starknet. Starknet verifies the proof and provides validated proof facts to the pool contract via syscall. A discovery service indexes encrypted on-chain storage so wallets can efficiently sync their notes without scanning the full chain.

Architecture

graph LR
    subgraph Offchain
        Wallet([Wallet])
        SDK[SDK]
        Discovery[Discovery]
        Proving[Proving]
    end

    subgraph Onchain
        Contract[Privacy Pool]
        Anonymizers[Invoke Anonymizers]
    end

    Wallet --> SDK
    SDK --> Discovery
    SDK --> Proving
    SDK --> Contract
    Discovery --> Contract
    Proving --> Contract
    Contract --> Anonymizers

Loading

• SDK — Orchestrates private transfers (register, transfer, discover)
• Discovery Service — Indexes encrypted on-chain storage for efficient wallet sync
• Proving Service — Executes actions in virtual Starknet blocks and returns validity proofs + proof facts to the SDK
• Privacy Pool Contract — Source of truth for actions, storage layout, cryptography
• Invoke Anonymizers — External contracts callable from within a private transaction (e.g. swap executors)

Compatibility matrix

All components in a row are tested together. Use matching revisions when deploying.

Component	Docs	Tag
Transaction Prover	README	ghcr.io/starkware-libs/starknet-privacy/transaction-prover:PRIVACY-0.14.3-RC.2
Proof Interceptor†	README	ghcr.io/starkware-libs/starknet-privacy/proof-interceptor:PRIVACY-0.14.3-RC.2
Discovery Service	README	ghcr.io/starkware-libs/starknet-privacy/discovery-service:PRIVACY-0.14.3-RC.2
Pathfinder*	docs	eqlabs/pathfinder:v0.22.7
SDK	README	PRIVACY-0.14.3-RC.2

* For the transaction prover to work correctly with Pathfinder, set PATHFINDER_STORAGE_STATE_TRIES=10000.

† Optional deposit-screening sidecar to the transaction prover; deploy only for screening-enabled pools.

Contracts

Contract	Docs	Tag	Class Hash
Privacy Pool	README	PRIVACY-0.14.3-RC.0	0x52107fadffab71bdcbb6b2ccb68ba3e1b5558d94036538053e159d3076ad633
Ekubo Anonymizer	README	PRIVACY-0.14.3-RC.0	0x2a4ac595283d4d64b9952f5ef5c0da1775bfdb7c9d92237524a21dd8d19ebd7
Vesu Anonymizer	README	PRIVACY-0.14.3-RC.0	0x3751128dc3ebd36215f982766f14aaca8f78793e4b0f42a73e49372a8e24aae

Repository map

Directory	Description
packages/privacy/	Cairo smart contract (README)
crates/discovery-core/	Core discovery logic & cryptography (README)
crates/discovery-service/	HTTP discovery service (RPC-backed) (README)
sdk/	TypeScript SDK for private transfers (README)
e2e/	End-to-end tests & devnet fixture generation (README)
deploy/discovery-service/	Dockerfile & deployment (README)
lean/	Formal verification (Lean)
demo/	Web demo application
scripts/	Utility scripts (devnet, deployment, etc.)
docs/	Audit reports & security docs (audit)
crates/discovery-service/specs/	Discovery service specifications (README)

Prerequisites

Cairo

Install Scarb and Starknet Foundry via starkup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.dev | sh

Rust

Stable toolchain. Install via rustup if needed.

Node.js

Version 20 or later.

E2E tests

See e2e/README.md for additional setup requirements (devnet, .env generation, built artifacts).

Build and test

scarb build && scarb test          # Cairo contract
cargo build && cargo test          # Rust crates
cd sdk && npm ci && npm test       # TypeScript SDK
cd e2e && npm ci && npm test       # E2E

License

Apache 2.0

Audit

Find the latest audit report in docs/audit.

Security

For more information and to report security issues, please refer to the security documentation.