strk20-privacy

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

STRK20 是一个已在主网运行、基于 note（UTXO）的隐私池，适用于 Starknet 上的任意 ERC-20。它作为合约运行在 Starknet 本身，使用现有钱包和现有流动性，并内置合规路径。与固定面额的混币器不同，note 可承载任意金额，并自动处理找零。用户将代币存入池中，形成加密 note；使用链上 STARK 证明验证进行私密交易；需要透明度时，再将代币提取出来。

完整文档页面原样保存在 references/ 中。以下各节是精简版索引。若某项细节至关重要（如地址、版本或 API 形式），请打开对应的参考页面。

先选择路由

目标	路由	技能
在用户钱包之上构建私密 dapp（DeFi、消费应用、游戏）	Starknet Wallet API；根据状态生命周期选择 invoke 辅助工具或 shadow account	strk20-wallet-api
私密 DeFi 流程调用的 Cairo 适配器	Anonymizer 合约（privacy_invoke）	strk20-anonymizer-contracts
隐私钱包，或持有自有密钥的后端	Privacy SDK（createPrivateTransfers）	strk20-privacy-sdk
嵌入式钱包或 AA 产品（Privy、Cartridge、chipi、cavos、Dynamic）	这些产品管理用户密钥，目前尚未启用隐私功能。应将产品视为密钥持有方，并选择 SDK 路由	strk20-privacy-sdk
在持久的、基于账户的应用活动期间隐藏与主钱包的关联	面向 dapp 的 Stable Wallet API shadow account；面向持有密钥的钱包和后端的 Privacy SDK	strk20-wallet-api 或 strk20-privacy-sdk
从 EVM 钱包（USDC）注资或提取到 EVM 钱包	通过 Circle CCTP 使用 Privacy Bridge	见下文「生态系统」
自行运行证明生成	本地 Docker prover 或通过 SSH 连接的远程主机；仍需进行筛查	部署使用 strk20-local-prover，钱包接入使用 strk20-privacy-sdk

文档中的经验法则：选择能让用户密钥留在正确位置的最精简路由。面向用户的 dapp 优先使用 Wallet API。切勿向普通 dapp 用户索要其查看密钥。对于私密 DeFi，无状态原子操作使用应用专用 invoke 辅助工具；持久化头寸或需要返回的假名身份，则使用规范的 shadow-account 基础设施。编写 Cairo 前先检查是否有官方集成路径：AVNU 提供私密兑换。

编码前先梳理信任边界

对于选定的路由，说明由谁持有签名密钥和查看密钥、由谁发现 note、由谁构造私密操作、由谁生成证明，以及由谁提交操作。列出能够观察请求的钱包、RPC、relayer、prover、筛查服务和应用运营方。最后附上隐藏与可见内容对照表，并列出仍需通过实时验证确认的钱包版本、软件包版本、地址、审计情况和网络假设。

一屏了解其工作原理

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

隐藏与可见：务必明确说明

资金池内隐藏的信息：发送方、接收方、令牌、数量、哪些 note 已被花费。对所有人可见的信息：注册事件、存款（存款人、令牌、数量）、取款（接收方、令牌、数量）、已发布的 nullifier（没有查看密钥就无法关联）、以明文显示的 open note 令牌和数量，以及时间。Paymaster 可以将提交地址与用户地址分离。

根据官方 agent-skill 仓库的说明：切勿将资金池活动归因于交易的发送方。私密交易会经过中继，因此对每位用户而言，交易发送方都是中继者的账户。应从资金池的 Deposit 事件读取每位用户的活动（第一个索引键），切勿从交易信封读取。

文档明确列出的已知限制。无论构建或撰写什么内容，都要重申这些限制：

• 通道开启操作可被关联。在同一笔交易中或短时间内开启通道并转移资金，可能会将接收方与公开活动关联起来。请将设置和转移分散到不同时间。
• 有辨识度的数量或快速转入转出模式会缩小匿名集。
• 边缘信息本就是公开的。只有资金池内部的转移会加密。

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

• 入金时筛查：每笔入金都会经过 FPI 筛查，并在链上验证签名。没有任何证明路径可以绕过这一步。
• 事后选择性披露：注册时，用户的私密查看密钥会使用与通道相同的临时 ECDH 方案托管给审计员的公钥。审计员密钥由治理机制设定，并支持门限密钥。仅在合法请求下，才会针对相关用户进行披露。不存在大规模监控模式。
• 查看密钥只能读取，不能支出。审计员密钥遭到泄露会破坏机密性，但不会影响资产托管。
• 对外宣传时，应采用“默认私密，需要时可披露”的表述。不要把密钥托管称为后门，也不要夸大其作用。边界信息（入金、提现、时间）是公开的。

路线状态（截至 2026-09-29 的快照，请在依赖前核实）

• Stable Wallet API 0.10.4 和 starknet.js 10.8.0 支持影子账户。Starknet.js 文档说明 Ready 和 Xverse 支持 STRK20。应检测已连接钱包公布的能力，而不是根据品牌推断是否支持。

• 影子账户在 RC.4 及更早的文档中称为私密子账户，可在账户活动期间隐藏其与主钱包的关联。Privacy SDK 0.14.3-rc.8 使用 RC.5 引入的名称：build().shadowAccounts(dappName)、shadowAccountAnonymizerAddress，以及 Cairo 包 shadow_account_anonymizer。重命名后的视图和事件使用新的选择器，因此 RC.5 需要升级后的匿名化器；跨升级版本的索引器必须同时匹配两种事件键。稳定版 @starknet-io/types-js 0.10.4 和 starknet.js 10.8.0 已包含该操作和承诺方法。要求钱包声明支持 Wallet API 0.10.4 或更高版本，并处理不支持方法的响应。底层 SDK 仍是候选发布版；其发布状态并不意味着稳定版 Wallet API 路线属于预发布版本。

  canonical ShadowAccountAnonymizer 部署在 Mainnet 的 0x04f33230dc57855c6e7eabe66dfa0fde82c5458fd0e54827cdb7cb4c474888a7 和 Sepolia 的 0x010a2285310c107c731d997afc147afb7495daff6397c2d242133d9fe8d9b147。 发布前请重新核对当前的合约地址页面。

  只有 nonce 是新的，影子账户才是全新的。其与主钱包之间的资金关联会被隐藏，但只要重复使用同一个 (dappName, nonce) 账户，影子地址、dapp 调用、余额、头寸、事件和时间信息仍然是公开的，并且可以相互关联。输入资产可以先存放在加密池的备注中。资产和头寸由影子账户持有期间都是公开的。归集会将它们转回一条开放备注，其中所有者关联会被隐藏，但代币和金额仍然公开。对于选定的集成路线，请参阅 Wallet API 技能中的 references/starknet-wallet-api__shadow-accounts.md，或 SDK 技能中的 references/shadow-accounts.md。

• Privacy Bridge（通过 Circle CCTP 在 EVM USDC 与资金池之间转移）是开源的早期项目。将其纳入规划前，请先阅读其 README。

• 文档中的发布检查清单要求：发布前核实钱包支持情况、API 版本、合约地址和合规假设。

生态系统

• 文档：https://strk20-by-example.org（可供 Agent 读取，路径为 /llms.txt 和 /llms-full.txt；在任意页面的 URL 后追加 .md，即可获取原始 Markdown）。产品 网站：https://strk20.starknet.io。
• 代码：starkware-libs/starknet-privacy（采用 Apache-2.0 许可的 monorepo，包含 TypeScript SDK、资金池合约和匿名化工具参考包）， starkware-libs/privacy-bridge、Akashneelesh/strk20-starter-kit（预先接入 Wallet API 的 Next.js starter）、Akashneelesh/awesome-strk20。
• Agent 技能：npx skills add welttowelt/strk20-skills。这些技能提供此 路由器，以及针对特定路由的 Wallet API、Cairo 辅助工具、SDK 和证明者指南。
• 创业公司征集计划：https://strk20.starknet.io/rfp（26 个未解决的问题陈述）。孵化器：https://proof.starknet.io。品牌工具包： https://strk20.starknet.io/brand.md 以及 /brand/tokens.json。

快速刷新时效性信息

在引用版本、包路径、Wallet API 状态或资金池地址之前，请从此技能目录运行附带的检查器：

python3 scripts/check_freshness.py

添加 --quick 可跳过 32 个逐页可用性请求。退出代码 1 表示某项已检查信息发生变化。退出代码 2 表示查询失败，结果不完整。检查器改编自官方集成技能。 它无法验证钱包的推出情况或合约审计状态，因此请手动检查相关来源。

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

此技能涵盖文档中说明的路径。如果遇到超出这些范围的情况，请停止操作，不要猜测：编造地址、手动设计证明路径或虚构 API 结构，都会比直接询问更浪费开发者的时间。请明确说明阻碍，并告知用户团队会直接答复：

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

遇到以下情况时，请升级处理，而不是自行发挥：

• 目标与路由表中的任何一行都不匹配，或者两个路由看起来都不合适。
• references/compliance.md 未解答的合规、审计或筛查问题。
• 无法通过公开来源确认的路由状态或生态系统相关声明。

移交问题时，请在一条消息中提供团队可据此采取行动的信息：准确的错误文本、失败的文件或调用、正在使用的包和钱包版本，以及无法验证的假设。

references/

• what-is-strk20.md，简介、生命周期、构建模块
• builder-privacy-overview.md，决策指南、所有路由、经验法则
• overview.md，精简版路由选择器和 starter kit
• notes-and-nullifiers.md，UTXO 模型、开放笔记、note_id 和 nullifier 的推导
• viewing-keys.md，屏蔽、ECDH、审计员托管
• channels-and-subchannels.md，通道、子通道、发现扫描
• actions-and-proofs.md，阶段表、余额不变量、证明流水线
• compliance.md，筛查、托管密钥、可见性表、局限性
• agent-skill.md，官方集成 Agent 技能
• contract-addresses.md，当前 Mainnet 和 Sepolia 上的资金池和匿名化工具部署