SuperAPI AI 工具集

strk20-anonymizer-contracts

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

匿名化合约(anonymizer contracts),也叫 helper 合约,是私有资金与外部世界(DEX、借贷金库、托管)交互而不暴露交互者身份的方式。本技能用于编写、审查或审计这类 Cairo 合约。完整文档页与完整 Cairo 源码位于 references/ 目录。

核心模式:原子三明治

  1. 从池中提取(withdraw from pool)
  2. helper 执行操作(helper does something)
  3. 将结果存入开放票据(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),但并无强制要求。

五条规则

  1. 精确返回一个 Span<OpenNoteDeposit>。返回其他任何内容,或带有尾部垃圾数据,都会让池拒绝该调用。
  2. 授权,而不是转账。池在应用存款时自行执行拉取。
  3. 空 span 是合法的。它表示“不记入任何东西”,用于暂存资金的步骤(参见 escrow 的存款分支)。
  4. 用余额差额计量输出。绝不要信任外部协议的返回值:
balance_before = out_token.balance_of(helper)
...external call...
out_amount = out_token.balance_of(helper) - balance_before   // u256 → u128, checked

这适用于任何协议,能处理转账收费代币,并且恰好记入池实际能拉取的金额。

  1. 每笔交易仅一次外部调用。由协议强制,且预算与 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。在适配之前请在那里核实当前源码。