Starknet privacy docs by maya-starkware · Pull Request #1747 · starknet-io/starknet-docs

maya-starkware · 2026-03-19T11:40:06Z

No description provided.

…-enthusiast copy

ob1337 · 2026-03-24T18:04:25Z

+
+Use the **Scarb / Cairo versions required by the repo** (see `Scarb.toml` and the README)—if the project pins an older or newer Scarb, switch with `asdf` per the [appendix](/build/quickstart/appendix) or the README.
+
+## 3. Rust (client prover)


This doesn't say how to install a client prover, its merely rust. There is not even reference to which repo the prover sits at. Addition required.

ob1337 · 2026-03-24T18:06:03Z

+cargo build --release
+```
+
+## 4. Build Cairo packages


Sections 4-6 are redundant. For 4 and 5 - I'm not following which packages requires building/testing and why. Seems like this refers to general abilities of scrab and snforge. Better to send the reader to these tools (if needed) and explain where in the flow they would come at (Are they relevant for proofs generation?)

Section 6 is just "if you want to also have another tool" - why its here?

ob1337 · 2026-03-24T18:07:32Z

+
+## Prerequisites
+
+Complete [Install and build](/build/starknet-privacy/installation) (Scarb, Foundry, Devnet, and Rust if the prover is in-repo).


Installation doesn't explicitly say how to install devnet, though (i believe starkup indeed installs it but worth to mention this tool there so the reader won't be confused)

Also - Starknet devnet is not a node. Its a local simulation tool. You want them to install devnet or to install a node? Very different things

ob1337 · 2026-03-24T18:09:28Z

+2. Builds client-side actions and generates a **ZK proof**.
+3. Submits the transaction (directly or via paymaster flow).
+
+Follow the README’s **first transaction** or **e2e** example.


which readme??

ob1337 · 2026-03-24T19:55:10Z

+
+## Action ordering
+
+Fixed order reduces attack surface:


which attack? On what?

ob1337 · 2026-03-24T19:55:43Z

+
+## Per-token balance
+
+Within one transaction, a **temporary balance** per token tracks: deposits and spent notes **increase** it; new notes and withdrawals **decrease** it. It must never go negative and must end at **zero** so all tokens are accounted for.


WDYM by must end with 0?

ob1337 · 2026-03-24T19:57:28Z

+icon: microchip
+---
+
+Proofs are generated by **executing Cairo in a simulated Starknet environment** tied to a recent block, then proving that execution with **Stwo**—the same prover family used for Starknet block proving.


I would add details on the differences between the simulated Starknet environment and a real Starknet block, builtins we support/don't support etc.

ob1337 · 2026-03-24T20:02:10Z

+
+## Open notes
+
+An **open note** reserves **salt = 1**, stores **amount 0** initially, and keeps **token** and **depositor address** in dedicated storage. The user’s proof **creates** the empty open note; a **trusted helper contract** (invoked in the same transaction) performs the swap and calls the pool to **fill** the open note **without** a new ZK proof for that fill.


Any link to an example of such a contract? I think it will help understand the flow

maya-starkware · 2026-03-31T09:20:09Z

Addressed all review comments for #1747 in latest push.

What was updated

overview.mdx: replaced large comparison table with link to privacygrid.dev, tightened “why Starknet privacy” framing.
installation.mdx: removed redundant generic sections; added concrete file checklist (README.md, Scarb.toml, snfoundry.toml, rust-toolchain.toml, Cargo.toml, workflows).
quickstart.mdx: clarified Devnet is a simulation tool (not full node), added explicit --url usage to avoid sncast network ambiguity, tightened reproducible flow.
architecture.mdx: clarified pool vs verifier roles.
discovery.mdx: explicitly documented directional channels (sender -> recipient) and why.
transaction-flow.mdx: clarified ordering rationale and “temporary balance must end at 0”.
proving.mdx: added practical “how to generate proof” direction and “simulated vs real execution” distinctions.
anonymous-defi.mdx: added section for helper-contract/example references.
Please re-check and I can apply any remaining wording tweaks quickly.

…pers

ob1337 · 2026-04-06T12:33:58Z

+This section sets expectations so readers are not asked to follow steps that assume unpublished code.
+
+- **In scope here:** the **protocol** as specified in the research paper—notes, channels, discovery, compliance, transaction ordering, security considerations—so curious readers, partners, and enterprises can understand how Starknet Privacy works **before** touching an implementation.
+- **Not in this first wave of docs:** install scripts, devnet quickstarts, repository layout, SDK usage, or proving-service operations. Those belong with the **reference implementation** when it is **open sourced**, which is planned for a **later phase** of the Starknet Privacy rollout (not expected before mainnet).


This paragraph is horrible. Why go into the specifics on things that are not in scope? And how a sentence like "not expected before mainnet" is understandable to a potential reader 2 months from now?

ob1337 · 2026-04-06T12:34:50Z

+
+- **In scope here:** the **protocol** as specified in the research paper—notes, channels, discovery, compliance, transaction ordering, security considerations—so curious readers, partners, and enterprises can understand how Starknet Privacy works **before** touching an implementation.
+- **Not in this first wave of docs:** install scripts, devnet quickstarts, repository layout, SDK usage, or proving-service operations. Those belong with the **reference implementation** when it is **open sourced**, which is planned for a **later phase** of the Starknet Privacy rollout (not expected before mainnet).
+- **Proving in practice:** generating proofs is **required** for normal private transfers; this site explains *why* and *how it fits the protocol*. Exact commands, crates, and integration paths will ship alongside the public repo and SDK.


"public repo" - which repo? (I know, but the reader won't). - The starknet privacy repo is published and referenced from multiple places, so this is very confusing. Also, again, too many details

ob1337 · 2026-04-06T12:37:01Z

+
+## Pool and verifier
+
+In many deployments, the privacy pool entrypoint and proof verification logic are composed as separate contracts/modules (for upgradeability and audit boundaries), even when docs describe them as one protocol surface. So conceptually: **the pool enforces state transitions, and proof verification gates those transitions**.


I guess things are different in our deployment? Why not mention it explicitly if so?

ob1337 · 2026-04-06T12:38:02Z

+
+## Client-side proving
+
+Users build client actions and generate a proof in a virtual Starknet execution environment anchored to a recent block.


At first phase its mostly distinguished operators that do it on behalf of the users, this sounds like generate proof is openly available

ob1337 · 2026-04-06T13:31:16Z

+The virtual environment is chain-anchored but not a full sequencer runtime. In practice:
+
+- storage and contract calls are evaluated against an anchored state snapshot,
+- only the syscalls and builtins implemented by the project runtime are available,


WDYM by "project runtime"?

ob1337 · 2026-04-06T13:33:41Z

+
+## Example reference shape: Vesu lending helper
+
+[Vesu](https://vesu.xyz) is a permissionless lending protocol on Starknet built around **tokenized vaults** (ERC-4626 / SNIP-22 style): depositing **underlying** mints **share** tokens (vTokens); withdrawing **burns** shares and returns underlying. A **Vesu lending helper** illustrates the same **open-note + Invoke** pattern as a swap helper, but the external calls are **`deposit`** / **`withdraw`** on the vToken contract instead of a swap.


This... isn't related to privacy at all, is it?

If we can't share a reference contract, better to just omit it and that's it

ob1337 · 2026-04-06T13:36:08Z

+
+After executing the lending call, the helper compares **output token balance before and after** to obtain **`out_amount`**, asserts it is non-zero, **approves the privacy pool** (the **caller**) to transfer that amount, and returns a span of **`OpenNoteDeposit { note_id, token: out_token, amount: out_amount }`** so the pool can **fill** the previously created open note.
+
+Typical **preconditions** (enforced with explicit errors) include: non-zero tokens and amount; `in_token != out_token`; on deposit, `out_token` must be a vToken; on withdraw, `in_token` must be a vToken; the helper must hold enough input balance for the requested `assets`.


what's wrong with in_token=out_token? If someone wants a DeFi operation for Arbitrage that starts and ends with USDC, why we ban it?

ob1337 · 2026-04-06T13:41:22Z

+
+Typical **preconditions** (enforced with explicit errors) include: non-zero tokens and amount; `in_token != out_token`; on deposit, `out_token` must be a vToken; on withdraw, `in_token` must be a vToken; the helper must hold enough input balance for the requested `assets`.
+
+### Interface sketch (Cairo)


Do you expect people to write their own adapter-contracts? If so, providing ABI of three function is not enough. IF not, this entire section is redundant IMO

ob1337 · 2026-04-06T13:43:46Z

+title: Channels, subchannels, and note discovery
+description: Location-indexed discovery and directional channels
+icon: magnifying-glass
+---


"Subchannel" is never explained in this page, only referenced. (This page was actually much better in the previous iteration where there were many more details)

* Add Starknet Privacy documentation section * Move Starknet Privacy to Learn; update nav and homepage * Starknet Privacy docs: under Learn, overview comparison grid, privacy-enthusiast copy * Address PR #1747 privacy docs review comments * Starknet Privacy: protocol-only docs, open notes + anonymous DeFi helpers * Address Apr 6 review comments on PR #1747 * rebranded helper contract to anonymizing contract --------- Co-authored-by: Maya Dotan <maya@MAC-MAYADO.local>

Maya Dotan added 3 commits March 19, 2026 12:45

Add Starknet Privacy documentation section

4f19d1b

Move Starknet Privacy to Learn; update nav and homepage

6911125

Starknet Privacy docs: under Learn, overview comparison grid, privacy…

9981abf

…-enthusiast copy

mintlify Bot deployed to staging March 19, 2026 11:41 View deployment

ob1337 reviewed Mar 24, 2026

View reviewed changes

Address PR #1747 privacy docs review comments

efc7e4a

mintlify Bot deployed to staging March 31, 2026 09:17 View deployment

Starknet Privacy: protocol-only docs, open notes + anonymous DeFi hel…

60daf6a

…pers

mintlify Bot deployed to staging April 6, 2026 09:27 View deployment

ob1337 reviewed Apr 6, 2026

View reviewed changes

Address Apr 6 review comments on PR #1747

09f03cb

mintlify Bot deployed to staging April 27, 2026 11:20 View deployment

ob1337 merged commit 9dc4a3b into main Apr 27, 2026
2 of 3 checks passed

ob1337 deleted the starknet-privacy-docs branch April 27, 2026 14:53


		Use the Scarb / Cairo versions required by the repo (see `Scarb.toml` and the README)—if the project pins an older or newer Scarb, switch with `asdf` per the [appendix](/build/quickstart/appendix) or the README.

		## 3. Rust (client prover)


		## Prerequisites

		Complete [Install and build](/build/starknet-privacy/installation) (Scarb, Foundry, Devnet, and Rust if the prover is in-repo).


		## Per-token balance

		Within one transaction, a temporary balance per token tracks: deposits and spent notes increase it; new notes and withdrawals decrease it. It must never go negative and must end at zero so all tokens are accounted for.


		## Open notes

		An open note reserves salt = 1, stores amount 0 initially, and keeps token and depositor address in dedicated storage. The user’s proof creates the empty open note; a trusted helper contract (invoked in the same transaction) performs the swap and calls the pool to fill the open note without a new ZK proof for that fill.


		## Pool and verifier

		In many deployments, the privacy pool entrypoint and proof verification logic are composed as separate contracts/modules (for upgradeability and audit boundaries), even when docs describe them as one protocol surface. So conceptually: the pool enforces state transitions, and proof verification gates those transitions.


		## Client-side proving

		Users build client actions and generate a proof in a virtual Starknet execution environment anchored to a recent block.


		## Example reference shape: Vesu lending helper

		[Vesu](https://vesu.xyz) is a permissionless lending protocol on Starknet built around tokenized vaults (ERC-4626 / SNIP-22 style): depositing underlying mints share tokens (vTokens); withdrawing burns shares and returns underlying. A Vesu lending helper illustrates the same open-note + Invoke pattern as a swap helper, but the external calls are `deposit` / `withdraw` on the vToken contract instead of a swap.


		After executing the lending call, the helper compares output token balance before and after to obtain `out_amount`, asserts it is non-zero, approves the privacy pool (the caller) to transfer that amount, and returns a span of `OpenNoteDeposit { note_id, token: out_token, amount: out_amount }` so the pool can fill the previously created open note.

		Typical preconditions (enforced with explicit errors) include: non-zero tokens and amount; `in_token != out_token`; on deposit, `out_token` must be a vToken; on withdraw, `in_token` must be a vToken; the helper must hold enough input balance for the requested `assets`.


		Typical preconditions (enforced with explicit errors) include: non-zero tokens and amount; `in_token != out_token`; on deposit, `out_token` must be a vToken; on withdraw, `in_token` must be a vToken; the helper must hold enough input balance for the requested `assets`.

		### Interface sketch (Cairo)

Conversation

maya-starkware commented Mar 19, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maya-starkware commented Mar 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants