strk20-anonymizer-contracts

STRK20 匿名化合约（privacy_invoke）

匿名化合约也称为辅助合约，可让私有资金与外部世界（DEX、借贷金库、托管服务）交互，而不暴露交互背后的身份。完整文档页面及完整 Cairo 源码位于 references/。

编写 Cairo 之前先确定路由。若需要由一个共享调用方执行原子操作，并立即将其输出返回到私有票据中，请使用辅助合约。若每位用户都需要一个稳定的假名地址，以便在多笔交易中持有份额、债务、NFT、奖励或其他状态，请通过 strk20-wallet-api 使用规范的 ShadowAccountAnonymizer。如果目标协议具有可直接调用的常规入口点，那么即使 dapp 使用影子账户，也不需要专门为该协议编写辅助合约。

模式：原子夹层操作

withdraw from pool  →  helper does something  →  deposit result to an open note

1. 池将输入代币提现到辅助合约。这是一次普通的公开转账，因此观察者只会看到池向辅助合约付款，而不会知道是谁发起的。
2. 池通过协议的 INVOKE_SELECTOR 调用辅助合约的 privacy_invoke 入口点。
3. 辅助合约执行操作，授权池提取输出，并返回一个 Span<OpenNoteDeposit>，告知池应将哪些代币和金额记入哪些开放票据。

输出会存入开放票据。其金额在执行时公开计量，而所有者仍保持隐藏。所有操作都在一笔交易中完成。任何环节发生回滚都会中止整个池交易，不会有资金转移。

合约接口

池会将 calldata 直接反序列化为 privacy_invoke 的参数，并将返回值反序列化为：

/// From privacy::objects
pub struct OpenNoteDeposit {
    pub note_id: felt252,      // the open note to credit
    pub token: ContractAddress,
    pub amount: u128,
}

签名由你设计。已发布的示例通常会将 operation 风格的参数放在首位（Vesu、托管服务），但并无强制要求。

五条规则

1. 返回值必须恰好是 Span<OpenNoteDeposit>。 返回其他内容或尾随垃圾数据，都会导致池拒绝调用。
2. 授权，不要转账。 池在应用存款时会自行提取资金。
3. 空 span 有效。 它表示“什么也不记入”，适用于暂存资金的步骤（参见托管服务的存款环节）。
4. 通过余额差额计量输出。 绝不要信任外部协议的返回值：

   balance_before = out_token.balance_of(helper)
   ...external call...
   out_amount = out_token.balance_of(helper) - balance_before   // u256 → u128, checked
   

   这种做法适用于任何协议，能处理转账扣费代币，并且只会记入池实际可提取的金额。
5. 每笔交易只允许一次外部调用。 这是协议强制规定的，并且根据阶段表，该额度与 ComputeAndInvoke 共同使用。

实例讲解。了解来源

Helper	来源	说明内容
EchoHelper	官方单体仓库测试契约	最小接口：输入 calldata，输出 span
SwapHelper	官方单体仓库模拟实现（mock_swap_executor）	DEX 教程模板：在部署时固定 AMM 地址和选择器，通过通用的 call_contract_syscall 调用合约，计算余额变化，添加 u256→u128 溢出保护和 ZERO_OUT_AMOUNT 检查
Ekubo swap anonymizer	官方参考包（packages/ekubo_swap_anonymizer）	生产级 DEX 参考实现：单跳 Ekubo 兑换，仅支持全额兑换。将模拟模板适配到线上 AMM 时，可参考此实现
VesuLendingHelper	官方参考包（vesu_lending_anonymizer）	ERC-4626/SNIP-22 金库：通过代币角色从一个入口执行存款和取款，无状态且无需许可（会授权给调用者，不会在交易之间持有任何内容），忽略份额返回值，改用余额变化。仅供参考：是否采用由应用团队决定，集成仍在进行中
Escrow	非官方网站示例，不在单体仓库中，也未经 Starkware 审查或审计	有状态 Helper：承诺值为 poseidon(ESCROW_COMMITMENT_TAG, secret)，固定池地址并检查 CALLER_NOT_PRIVACY，通过 claimed 标志防止重复领取，存款分支返回空 span
Outbound/InboundAnonymizer	starkware-libs/privacy-bridge	基于 Circle CCTP 的跨链配对实现。入站端将 privacy_invoke 与 privacy_compute 配对，在一笔交易中绑定经证明的消息和私密票据

官方 Agent 技能仓库的链接规则规定，面向开发者的输出中绝不能引用 escrow 页面。 其注意事项：仅将 escrow 作为模式示例引用，绝不能将其称为已发布的包。

新建 Helper 的安全检查清单

• 有状态的 Helper（会在交易之间持有资金）？在构造函数中固定池地址，并在 privacy_invoke 中断言调用者身份。无状态 Helper 可以保持无需许可，因为它们在交易期间持有的任何内容都会在同一笔交易中由池取走。
• 验证输入：代币地址和金额均非零，且 in_token != out_token。
• 将输出变化量从 u256 → u128 转换，并提供明确的错误；若输出为零则回滚，而不是记入空票据。
• 让外部回滚继续向上传递。终止池交易是安全的处理方式。
• 票据金额为 u128。以 u256 进行的金库计算必须能容纳在此范围内，否则调用会回滚。
• 所有权：匿名化合约由应用团队编写、审查和审计。官方 STRK20 Agent 技能正是出于这个原因而拒绝生成 Cairo 代码。如果 Claude 起草了此类代码，必须标注为草稿，并在部署前交由团队审查和审计。对其运行 cairo-security 技能。

Dapp 端

Dapp 通过 Wallet API 使用两个操作调用 Helper：一个金额为 "OPEN" 的 transfer（创建开放票据），以及一个指定 Helper 的 invoke，其 calldata 中包含 ${openNoteIds[0]}。Calldata 的顺序必须与 Helper 的 privacy_invoke 签名一致。详情和试运行流程请参阅 strk20-wallet-api 技能。仅兑换无需自定义 Helper，因为 AVNU 提供了执行器。

受阻？请告知用户联系 STRK20 团队

本技能涵盖文档中说明的路径。遇到超出这些范围的情况时，请停止操作，不要猜测：捏造地址、手写证明路径或臆造 API 结构，都会让构建者付出比询问更多的时间。请明确说明遇到了什么阻碍，并告知用户团队会直接答复：

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

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

• 某个协议的调用形式无法通过 privacy_invoke 表达，除非违反五条规则之一。
• 无法将余额变化与返回的 OpenNoteDeposit 值对应起来。
• 被封装的协议没有上游参考辅助工具，因此只能在此处臆造实现模式。
• 任何涉及资金的情况，只要无法满足上述安全检查清单要求。

转交问题时，请在一条消息中提供团队可据此采取行动的信息：完整错误文本、出错的文件或调用、正在使用的软件包和钱包版本，以及你无法核实的假设。

references/

• helpers__privacy-invoke.md，结构、规则、EchoHelper 源码
• helpers__swap-helper.md，SwapHelper 和 MockAMM 完整源码、余额变化惯用模式
• helpers__vesu-lending-helper.md，Vesu 官方参考资料、完整源码
• helpers__escrow.md，非官方有状态示例、完整源码

快照日期：2026-08-16。合约软件包位于 starkware-libs/starknet-privacy。修改前请在那里核实当前源码。