用途
匿名化合约(anonymizer contracts),也叫 helper 合约,是私有资金与外部世界(DEX、借贷金库、托管)交互而不暴露交互者身份的方式。本技能用于编写、审查或审计这类 Cairo 合约。完整文档页与完整 Cairo 源码位于 references/ 目录。
核心模式:原子三明治
- 从池中提取(withdraw from pool)
- helper 执行操作(helper does something)
- 将结果存入开放票据(deposit result to an open note)
池把输入代币提取给 helper。这是一笔普通的公开转账,因此观察者看到的是池付给了 helper,而不是谁发起了它。
池通过协议的 INVOKE_SELECTOR 调用 helper 的 privacy_invoke 入口点。
helper 完成工作,授权池拉取输出,并返回一个 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,
}
签名由你设计。已发布的示例惯例上以一个操作风格参数开头(Vesu、escrow),但并无强制要求。
五条规则
- 精确返回一个 Span<OpenNoteDeposit>。返回其他任何内容,或带有尾部垃圾数据,都会让池拒绝该调用。
- 授权,而不是转账。池在应用存款时自行执行拉取。
- 空 span 是合法的。它表示“不记入任何东西”,用于暂存资金的步骤(参见 escrow 的存款分支)。
- 用余额差额计量输出。绝不要信任外部协议的返回值:
balance_before = out_token.balance_of(helper)
...external call...
out_amount = out_token.balance_of(helper) - balance_before // u256 → u128, checked
这适用于任何协议,能处理转账收费代币,并且恰好记入池实际能拉取的金额。
- 每笔交易仅一次外部调用。由协议强制,且预算与 ComputeAndInvoke 按阶段表共同共享。
示例与来源
| Helper | 来源 | 教学点 |
|---|---|---|
| EchoHelper | 官方 monorepo 测试合约 | 最小接口:calldata 进,span 出 |
| SwapHelper | 官方 monorepo mock(mock_swap_executor) | 教程 DEX 模板:AMM 地址与 selector 在部署时固定,通用 call_contract_syscall,余额差额,u256→u128 溢出保护,ZERO_OUT_AMOUNT 保护 |
| Ekubo swap anonymizer | 官方参考包(packages/ekubo_swap_anonymizer) | 生产级 DEX 参考:单跳 Ekubo swap,仅支持全额兑换。在把 mock 模板适配到真实 AMM 时研究它 |
| VesuLendingHelper | 官方参考包(vesu_lending_anonymizer) | ERC-4626/SNIP-22 金库:通过代币角色在一个入口点完成存款与取款,无状态且无需许可(授权任何调用者,跨交易不持有任何东西),忽略份额返回值而采用差额。仅为参考示例:采用与否由应用团队决定,集成仍在进行中 |
| Escrow | 非官方站点示例,不在 monorepo 中,未经 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-skill 仓库的链接规则指出:绝不要在面向开发者的输出中引用 escrow 页面。其注意事项是:仅将 escrow 作为模式示例引用,绝不作为已发布包引用。
新 helper 的安全清单
- 有状态 helper(跨交易持有资金)?在构造函数中固定池地址,并在 privacy_invoke 中断言调用者。无状态 helper 可以保持无需许可,因为它们在交易中途持有的任何东西都会在同一笔交易中被池拉取。
- 校验输入:非零代币地址与金额,in_token != out_token。
- 将输出差额 u256 → u128 转换并给出显式错误,且在输出为零时回滚,而不是记入一个空票据。
- 让外部回滚向上传播。中止池交易是安全的结果。
- 票据金额是 u128。u256 的金库数学必须能装得下,否则调用会回滚。
- 所有权:匿名化合约是应用团队要编写、审查和审计的代码。官方 STRK20 agent skill 正是出于这个原因拒绝生成 Cairo。如果 Claude 起草了一份,请将其标记为草稿,并在任何部署之前交由团队审查与审计。对其运行 cairo-security 技能。
dapp 侧
dapp 通过 Wallet API 以两个动作触达 helper:一笔金额为 "OPEN" 的转账(创建开放票据),以及一个命名该 helper 的 invoke,calldata 中包含 ${openNoteIds[0]}。calldata 顺序必须与 helper 的 privacy_invoke 签名匹配。细节与 dry-run 流程位于 strk20-wallet-api 技能中。仅做兑换不需要自定义 helper,因为 AVNU 已提供执行器。
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。在适配之前请在那里核实当前源码。