strk20-privacy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

STRK20, Starknet privacy: router and mental model

STRK20，Starknet隐私方案：路由与心智模型

STRK20 is a live-on-mainnet, note-based (UTXO) privacy pool for any ERC-20 on Starknet. It runs as a contract on Starknet itself, on existing wallets and existing liquidity, with a built-in compliance path. Unlike a fixed-denomination mixer, notes carry arbitrary amounts and change is handled automatically. Users shield tokens into the pool as encrypted notes, transact privately with onchain STARK-proof verification, and unshield when they want transparency.

Full doc pages sit verbatim in

references/

. The sections below are a condensed map. When a detail is load-bearing (an address, a version, an API shape), open the reference page.

STRK20是Starknet上已上线主网、基于票据（UTXO）的隐私池，支持Starknet上任意ERC-20代币。它作为合约运行在Starknet本身，兼容现有钱包与流动性，内置合规路径。与固定面额的混币器不同，票据可承载任意金额，找零会自动处理。用户将代币加密为票据存入池内，通过链上STARK-proof验证进行私密交易，需要透明性时可解除隐私保护。

完整文档原样存放在

references/

目录下。以下是精简版概览。当涉及关键细节（如地址、版本、API结构）时，请查阅参考文档。

Pick the route first

先选择合适路径

Goal	Route	Skill
Private dapp (DeFi, consumer, games) on top of users' wallets	Starknet Wallet API, plus an anonymizer contract for protocol-specific DeFi	`strk20-wallet-api`
The Cairo adapter a private DeFi flow calls	Anonymizer contract ( `privacy_invoke` )	`strk20-anonymizer-contracts`
A privacy wallet, or a backend holding its own keys	Privacy SDK ( `createPrivateTransfers` )	`strk20-privacy-sdk`
Embedded-wallet or AA product (Privy, Cartridge, chipi, cavos, Dynamic)	These manage user keys and are not privacy-enabled today. Treat the product as the key-holder and take the SDK route	`strk20-privacy-sdk`
Hide the main-wallet link during account-based app activity	Shadow accounts, called private sub-accounts before SDK RC.5. SDK route shipped. Wallet API is in prerelease tooling, with wallet rollout unverified	`strk20-privacy-sdk`
Fund from or withdraw to an EVM wallet (USDC)	Privacy Bridge over Circle CCTP	see Ecosystem below
Operate proof generation yourself	Prover backend, screening still applies	`strk20-privacy-sdk`

Rules of thumb from the docs. Start with the narrowest route that keeps user keys in the right place. Wallet API first for user-facing dapps. Never ask a normal dapp user for their viewing key. For private DeFi, expect both a Wallet API flow and an app-specific anonymizer contract, and check for a first-party private path before routing anyone to an anonymizer: AVNU ships private swaps, so that flow needs no Cairo of your own.

目标	路径	技能
基于用户钱包构建私有去中心化应用（DeFi、消费类、游戏类）	Starknet Wallet API，加上针对特定DeFi协议的匿名化合约	`strk20-wallet-api`
私有DeFi流程调用的Cairo适配器	匿名化合约（ `privacy_invoke` ）	`strk20-anonymizer-contracts`
隐私钱包，或托管自身密钥的后端	隐私SDK（ `createPrivateTransfers` ）	`strk20-privacy-sdk`
嵌入式钱包或AA产品（Privy、Cartridge、chipi、cavos、Dynamic）	此类产品目前未启用隐私功能，需将其视为密钥托管方，采用SDK路径	`strk20-privacy-sdk`
在基于账户的应用活动中隐藏主钱包关联	影子账户（SDK RC.5版本前称为私有子账户）。SDK路径已发布，Wallet API处于预发布工具阶段，钱包部署情况尚未验证	`strk20-privacy-sdk`
从EVM钱包充值或提取USDC	基于Circle CCTP的隐私桥	见下方生态系统部分
自行生成证明	证明后端，仍需遵守筛查规则	`strk20-privacy-sdk`

文档中的经验法则：优先选择能将用户密钥妥善保管的最窄路径。面向用户的去中心化应用优先使用Wallet API。切勿向普通去中心化应用用户索要查看密钥。对于私有DeFi场景，需同时支持Wallet API流程和应用专属匿名化合约，且在引导用户使用匿名化合约前，先检查是否存在官方私有路径：例如AVNU已支持私有兑换，该流程无需自行编写Cairo代码。

Map the trust boundary before coding

编码前梳理信任边界

For the selected route, state who holds the signing key and viewing key, who discovers notes, who constructs the private action, who proves it, and who submits it. Name the wallet, RPC, relayer, prover, screening service, and app operators that can observe the request. End with a hidden-versus-visible table and list the wallet versions, package versions, addresses, audits, and network assumptions that still need live verification.

针对选定路径，明确谁持有签名密钥和查看密钥、谁发现票据、谁构建私密操作、谁生成证明、谁提交操作。列出可观察请求的钱包、RPC、中继器、证明器、筛查服务及应用运营商。最后附上隐私与可见内容对照表，并列出仍需实际验证的钱包版本、包版本、地址、审计情况及网络假设。

The mental model, one screen

心智模型概览

Note: an immutable record of (owner, token, u128 amount), stored encrypted. UTXO semantics, spent whole, change comes back as a new note. Open notes skip amount encryption (protocol salt
```
OPEN_NOTE_SALT
```
= 1, encrypted notes use salt ≥ 2) so a DeFi output amount can be filled in after proving.
Nullifier: a Poseidon hash bound to the note and the owner's private viewing key, published on spend. Deterministic, unique, unlinkable. The sender cannot compute it, so senders cannot watch for their payment being spent.
Viewing keypair
```
K = k·G
```
on the STARK curve, registered once via
```
SetViewingKey
```
and treated as immutable. Registration is a prerequisite: both sender and recipient must be registered before a private transfer, and only the recipient can register themselves (wallets do it on first use). Note data is hidden with domain-separated Poseidon masking, channel secrets come from ephemeral ECDH, and at registration
```
k
```
is also encrypted to the auditor's public key (the compliance escrow).
Channels are directional sender-to-recipient lanes with per-token subchannels and dense, WriteOnce note indices. Recipients discover funds by scanning only their own channels, so cost scales with your own activity, not pool volume. A deposit is a channel from yourself to yourself.
Transactions are batches of actions in fixed phases 0 to 7:
```
SetViewingKey
```
,
```
OpenChannel
```
,
```
OpenSubchannel
```
,
```
Deposit
```
,
```
UseNote
```
,
```
CreateEncNote
```
/
```
CreateOpenNote
```
,
```
Withdraw
```
,
```
InvokeExternal
```
/
```
ComputeAndInvoke
```
(phase 7 jointly limited to at most one). Per-token temporary balance may never go negative and must end exactly zero.
Proofs: the transaction executes in a virtual Starknet environment anchored to a recent block, then Stwo generates a STARK proof (~29 s on a 12-core / 46 GiB machine, hardware-dependent). Onchain checks before applying: program variant (
```
VIRTUAL_SNOS
```
), anchor within
```
proof_validity_blocks
```
of the tip (default 450 ≈ 15 min, governance-set), and the proven message hash must match the submitted actions.
Deposit screening: FPI screens the shielding address and signs every deposit, and the pool verifies that signature onchain. Protocol-level since the v0.14.3 upgrade, so it applies on every route, self-hosted provers included.

票据（Note）：记录（所有者、代币、u128金额）的不可变记录，加密存储。遵循UTXO语义，需全额消耗，找零以新票据形式返回。公开票据跳过金额加密（协议盐值
```
OPEN_NOTE_SALT
```
=1，加密票据使用盐值≥2），以便在证明完成后填充DeFi输出金额。
零知识证明标识符（Nullifier）：与票据及所有者私有查看密钥绑定的Poseidon哈希，在消耗票据时公开。具有确定性、唯一性、不可链接性。发送方无法计算该值，因此无法追踪自己的付款是否被消耗。
查看密钥对
```
K = k·G
```
基于STARK曲线，通过
```
SetViewingKey
```
注册后视为不可变。注册是前置条件：私密转账前，发送方和接收方均需完成注册，且仅接收方可自行完成注册（钱包首次使用时会自动完成）。票据数据通过域分离的Poseidon掩码隐藏，通道密钥来自临时ECDH，注册时
```
k
```
还会加密至审计方公钥（合规托管账户）。
通道（Channels）：定向的发送方到接收方通道，包含按代币划分的子通道及密集的一次性票据索引。接收方仅需扫描自身通道即可发现资金，因此成本与自身活动量相关，而非池内总交易量。存款是从自身到自身的通道。
交易：分为0至7固定阶段的批量操作：
```
SetViewingKey
```
、
```
OpenChannel
```
、
```
OpenSubchannel
```
、
```
Deposit
```
、
```
UseNote
```
、
```
CreateEncNote
```
/
```
CreateOpenNote
```
、
```
Withdraw
```
、
```
InvokeExternal
```
/
```
ComputeAndInvoke
```
（第7阶段最多只能执行其中一项）。每个代币的临时余额不得为负，且最终必须恰好为零。
证明（Proofs）：交易在锚定到近期区块的虚拟Starknet环境中执行，随后由Stwo生成STARK证明（在12核/46 GiB机器上约需29秒，具体取决于硬件）。链上应用前会检查：程序变体（
```
VIRTUAL_SNOS
```
）、锚定区块距离最新区块不超过
```
proof_validity_blocks
```
（默认450≈15分钟，由治理设置）、已证明的消息哈希必须与提交的操作匹配。
存款筛查：FPI会对存入地址进行筛查并为每笔存款签名，池内合约会在链上验证该签名。自v0.14.3版本升级后，此规则成为协议级要求，适用于所有路径，包括自托管证明器。

Hidden vs visible. Always be explicit

隐私与可见内容：务必明确区分

Hidden inside the pool: sender, receiver, token, amount, which notes were spent. Visible to everyone: registration events, deposits (depositor, token, amount), withdrawals (recipient, token, amount), published nullifiers (unlinkable without a viewing key), open-note token and amount in plaintext, and timing. A paymaster can decouple the submitting address from the user.

Per the official agent-skill repo: never attribute pool activity to a transaction's sender. Private transactions are relayed, so the sender is the relayer's account for every user. Read per-user activity from the pool's

Deposit

event (first indexed key), never from the transaction envelope.

Known limitations the docs state outright. Repeat them in anything you build or write:

Channel-open linkability. Opening a channel and moving funds in the same transaction or in tight succession can link a recipient to public activity. Spread setup and movement over time.
Distinctive amounts or rapid in-and-out patterns shrink the anonymity set.
The edges are public by design. Only movement inside the pool is encrypted.

池内隐藏内容：发送方、接收方、代币、金额、消耗的票据。所有人可见内容：注册事件、存款（存款方、代币、金额）、提取（接收方、代币、金额）、公开的零知识证明标识符（无查看密钥则无法关联）、公开票据的代币及金额明文、交易时间。支付方可以将提交地址与用户解耦。

根据官方Agent技能仓库：切勿将池内活动归因于交易的发送方。私密交易由中继器转发，因此所有用户的交易发送方均为中继器账户。需从池内的

Deposit

事件（首个索引键）读取用户活动，切勿从交易信封中获取。

文档明确列出的已知限制。在构建或撰写任何内容时需重复说明：

通道开启的可链接性：在同一交易或短时间内连续开启通道并转移资金，可能会将接收方与公开活动关联。请分开执行设置与资金转移操作。
独特金额或快速进出模式会缩小匿名集。
边缘环节设计为公开可见。仅池内的资金转移会被加密。

Compliance model (get this exactly right)

合规模型（务必准确理解）

Screening at the door: every deposit is FPI-screened and signature-verified onchain. No proving route bypasses it.
Selective disclosure after the fact: the user's private viewing key is escrowed to the auditor's public key at registration, using the same ephemeral ECDH scheme as channels. The auditor key is set by governance and supports threshold keys. Disclosure targets only users under a lawful request. There is no bulk-surveillance mode.
A viewing key can read, never spend. Auditor-key compromise would break confidentiality, never custody.
For public copy, the framing is "private by default, disclosable when required". Do not call the escrow a backdoor, and do not oversell. The edges (deposits, withdrawals, timing) are public.

入口筛查：每笔存款均需经过FPI筛查并在链上验证签名。任何证明路径都无法绕过此规则。
事后选择性披露：用户的私有查看密钥在注册时会托管至审计方公钥，采用与通道相同的临时ECDH方案。审计方密钥由治理设置，支持阈值密钥。仅针对合法请求下的用户进行披露。不存在批量监控模式。
查看密钥仅可读取，不可用于转账。审计方密钥泄露会破坏保密性，但不会影响资产托管安全。
公开文案需采用「默认私密，必要时可披露」的表述。切勿将托管称为后门，也不要过度宣传。边缘环节（存款、提取、时间）均为公开可见。

Route status (snapshot 2026-09-02, verify before relying on it)

路径状态（快照时间2026-09-02，使用前请验证）

Wallet API version 0.10.3. The official integration skill uses Ready as the tested dapp baseline and still marks Xverse's dapp-facing Wallet API in progress. Product docs also list Xverse for user privacy flows, so detect the connected wallet's capability instead of inferring it from the brand. Braavos and embedded-wallet providers are not privacy-enabled in the cited integration sources.
Shadow accounts, called private sub-accounts in RC.4 and older docs, hide the main-wallet link during account activity. Privacy SDK
```
0.14.3-rc.6
```
uses the names introduced in RC.5:
```
build().shadowAccounts(dappName)
```
,
```
shadowAccountAnonymizerAddress
```
, and the Cairo package
```
shadow_account_anonymizer
```
. The renamed views and event use new selectors, so RC.5 requires the upgraded anonymizer and an indexer spanning the upgrade must match both event keys. Stable
```
@starknet-io/types-js
```
0.10.3 lacks the route. The Wallet API 0.10.4 development spec, types-js 0.10.4 beta, and starknet.js 10.7.1 on npm
```
next
```
include the shadow-account action and commitment method. That proves client plumbing exists, not that a connected wallet implements it. Require the wallet to advertise the 0.10.4-rc.1 shadow-account schema or a compatible later version, then handle an unsupported-method response. The SDK is still a release candidate. Confirm the current API, wallet support, deployment, and audit readiness before shipping.
A shadow account is fresh only when the nonce is fresh. Its funding link to the main wallet is hidden, while the shadow address, dapp calls, balances, positions, events, and timing remain public and linkable for as long as that
```
(dappName, nonce)
```
account is reused. Inputs can start in encrypted pool notes. Assets and positions are public while held by the shadow account. Collection returns them to an open note whose owner link is hidden, while its token and amount remain public. See the SDK skill's
```
references/shadow-accounts.md
```
for the builder model, collection policies, test evidence, and launch gates.
Privacy Bridge (EVM USDC to and from the pool over Circle CCTP) is open source and early. Read its README before planning around it.
The docs' own launch checklist: verify wallet support, API versions, contract addresses, and compliance assumptions before launch.

Wallet API版本0.10.3。官方集成技能将Ready作为已测试的去中心化应用基准，Xverse面向去中心化应用的Wallet API仍处于开发中。产品文档也将Xverse列为用户隐私流程的支持方，因此需检测连接钱包的能力，而非仅根据品牌推断。Braavos及嵌入式钱包提供商在引用的集成来源中未启用隐私功能。
影子账户（RC.4及更早版本文档中称为私有子账户）可在账户活动期间隐藏主钱包关联。隐私SDK
```
0.14.3-rc.6
```
使用RC.5版本引入的命名：
```
build().shadowAccounts(dappName)
```
、
```
shadowAccountAnonymizerAddress
```
及Cairo包
```
shadow_account_anonymizer
```
。重命名后的视图和事件使用新选择器，因此RC.5版本需要升级后的匿名化合约，跨升级的索引器需匹配两种事件键。稳定版
```
@starknet-io/types-js
```
0.10.3不支持此路径。Wallet API 0.10.4开发规范、types-js 0.10.4测试版及npm
```
next
```
上的starknet.js 10.7.1包含影子账户操作及提交方法。这仅表明客户端 plumbing 已存在，不代表连接的钱包已实现该功能。需要求钱包声明支持0.10.4-rc.1影子账户规范或兼容的后续版本，同时处理不支持方法的响应。SDK仍处于候选发布阶段。发布前请确认当前API、钱包支持情况、部署状态及审计就绪情况。

影子账户仅在随机数新鲜时才是全新的。其与主钱包的资金关联会被隐藏，但影子地址、去中心化应用调用、余额、持仓、事件及时间仍保持公开且可关联，只要

(dappName, nonce)

账户被重复使用。输入可来自加密池内票据。影子账户持有资产和持仓期间，这些内容均为公开可见。归集操作会将资产返回至所有者关联被隐藏的公开票据，但代币及金额仍为公开可见。如需了解构建者模型、归集策略、测试证据及发布门槛，请查阅SDK技能的

references/shadow-accounts.md

文档。

隐私桥（基于Circle CCTP实现EVM USDC与池内的双向转移）为开源项目，尚处于早期阶段。规划前请阅读其README文档。
文档自带的发布检查清单：发布前验证钱包支持情况、API版本、合约地址及合规假设。

Ecosystem

生态系统

Docs: https://strk20-by-example.org (agent-readable at
```
/llms.txt
```
and
```
/llms-full.txt
```
, any page as raw Markdown by appending
```
.md
```
). Product site: https://strk20.starknet.io.
Code:
```
starkware-libs/starknet-privacy
```
(Apache-2.0 monorepo with the TypeScript SDK, pool contracts, and anonymizer reference packages),
```
starkware-libs/privacy-bridge
```
,
```
Akashneelesh/strk20-starter-kit
```
(Next.js starter with the Wallet API pre-wired),
```
Akashneelesh/awesome-strk20
```
.
Official integration agent skill:
```
npx skills add starkience/strk20-agent-skills
```
. It scans a repo, interviews the developer, picks a route, writes
```
STRK20_INTEGRATION_PLAN.md
```
, and executes on approval. It never writes Cairo and never touches key material.
Request for Startups: https://strk20.starknet.io/rfp (26 open problem statements). Incubator: https://proof.starknet.io. Brand kit: https://strk20.starknet.io/brand.md plus
```
/brand/tokens.json
```
.

文档：https://strk20-by-example.org（Agent可通过`/llms.txt`和`/llms-full.txt`读取，任何页面均可通过追加`.md`获取原始Markdown内容）。产品官网：https://strk20.starknet.io。
代码：
```
starkware-libs/starknet-privacy
```
（Apache-2.0协议的单体仓库，包含TypeScript SDK、池合约及匿名化参考包）、
```
starkware-libs/privacy-bridge
```
、
```
Akashneelesh/strk20-starter-kit
```
（预配置Wallet API的Next.js入门套件）、
```
Akashneelesh/awesome-strk20
```
。
官方集成Agent技能：
```
npx skills add starkience/strk20-agent-skills
```
。该技能可扫描仓库、与开发者沟通、选择路径、生成
```
STRK20_INTEGRATION_PLAN.md
```
并在获批后执行。它不会编写Cairo代码，也不会接触密钥材料。
创业征集（RFP）：https://strk20.starknet.io/rfp（包含26个待解决问题）。孵化器：https://proof.starknet.io。品牌套件：https://strk20.starknet.io/brand.md 及
```
/brand/tokens.json
```
。

Refresh fast-moving facts

更新快速变化的信息

Run the bundled checker from this skill directory before quoting a version, package path, Wallet API status, or pool address:

python3 scripts/check_freshness.py

Add

--quick

to skip the 30 per-page liveness requests. Exit code 1 means a checked fact moved. Exit code 2 means a lookup failed and the result is incomplete. The checker is adapted from the official integration skill. It cannot verify wallet rollout or contract audit status, so check those sources manually.

引用版本、包路径、Wallet API状态或池地址前，请运行本技能目录中的检查脚本：

python3 scripts/check_freshness.py

添加

--quick

参数可跳过每页30次的可用性请求。退出码1表示已检查的信息发生变化。退出码2表示查找失败，结果不完整。该检查脚本改编自官方集成技能。它无法验证钱包部署或合约审计状态，因此需手动检查这些来源。

Blocked? Tell the user to contact the STRK20 team

遇到阻塞？告知用户联系STRK20团队

This skill covers the documented paths. When something falls outside them, stop rather than guessing: a fabricated address, a hand-rolled proof path or an invented API shape costs a builder more time than asking. Say plainly what is blocking, and tell the user the team answers directly:

Telegram: @Akashneelesh, @adiihq, @starkience
The STRK20 Private Sprint page, which publishes these contacts. Availability may change, so confirm the page still lists them.

Escalate rather than improvise when:

The goal does not map onto a row of the route table, or two routes both look wrong.
A compliance, auditing or screening question that
```
references/compliance.md
```
does not answer.
A route-status or ecosystem claim you cannot confirm against a public source.

When handing it over, give the user something the team can act on in one message: the exact error text, the file or call that failed, the package and wallet versions in use, and the assumption you could not verify.

本技能仅覆盖文档中已记录的路径。当遇到文档外的情况时，请停止操作而非猜测：伪造地址、手动实现的证明路径或虚构的API结构会给开发者带来更多麻烦，不如直接咨询。请明确说明阻塞点，并告知用户团队会直接回复：

Telegram：@Akashneelesh、@adiihq、@starkience
STRK20 Private Sprint页面，该页面会公布这些联系方式。联系方式可能会变化，请确认页面仍列出这些信息。

出现以下情况时，请升级问题而非自行处理：

目标无法匹配路径表中的任何一行，或两条路径均不合适。
```
references/compliance.md
```
未解答的合规、审计或筛查问题。
无法通过公开来源确认的路径状态或生态系统声明。

移交问题时，请提供团队可直接处理的信息：确切的错误文本、失败的文件或调用、使用的包及钱包版本、无法验证的假设。

references/

```
what-is-strk20.md
```
, intro, lifecycle, building blocks
```
builder-privacy-overview.md
```
, decision guide, all routes, rules of thumb
```
overview.md
```
, condensed route chooser plus starter kit
```
notes-and-nullifiers.md
```
, UTXO model, open notes, note_id and nullifier derivations
```
viewing-keys.md
```
, masking, ECDH, auditor escrow
```
channels-and-subchannels.md
```
, channels, subchannels, discovery scan
```
actions-and-proofs.md
```
, phase table, balance invariant, proving pipeline
```
compliance.md
```
, screening, escrowed key, visibility table, limitations
```
agent-skill.md
```
, the official integration agent skill

```
what-is-strk20.md
```
：介绍、生命周期、构建模块
```
builder-privacy-overview.md
```
：决策指南、所有路径、经验法则
```
overview.md
```
：精简版路径选择器及入门套件
```
notes-and-nullifiers.md
```
：UTXO模型、公开票据、note_id及零知识证明标识符推导
```
viewing-keys.md
```
：掩码、ECDH、审计方托管
```
channels-and-subchannels.md
```
：通道、子通道、发现扫描
```
actions-and-proofs.md
```
：阶段表、余额不变性、证明流程
```
compliance.md
```
：筛查、密钥托管、可见性对照表、限制
```
agent-skill.md
```
：官方集成Agent技能