Vara.eth Contract Writer 是一项面向 Vara.eth 的 Rust Sails 合约编写与审查技能。其核心规则是把目标明确为 Vara.eth,而不是通用 Vara、通用 Gear 或 EVM Solidity,并使用带 ethexe 特性的 Sails 以及 Vara.eth 产物工作流。示例应保持最小、可运行,并明确说明生成的产物;当合约行为涉及部署、ABI、RPC 或运行时语义时,需要对照源映射进行验证。
环境方面,需要 Rust 工具链、通过 rustup target add wasm32v1-none 安装 wasm32v1-none,以及通过 cargo install sails-cli 安装 sails-cli。新合约使用 --eth 参数脚手架创建,例如以 cargo sails new counter --author "$AUTHOR" --username "$USERNAME" --eth 生成项目,并将生成的项目作为起点,在生成的 Rust 源码中修改服务、事件和程序状态,而不是另建并行结构。
依赖方面,Vara.eth 合约必须使用启用 ethexe 特性的 Sails,典型依赖块包含 sails-rs 0.10.1 并启用 ethexe 特性,以及 parity-scale-codec 和 scale-info。公开自定义类型需要编码和类型元数据时使用后两者。
合约结构上,清晰的 Sails 合约通常包含 #![no_std]、引入 sails_rs 的 cell::RefCell 和 prelude、持有服务状态的状态/数据结构、带 #[event] 的事件枚举、通过 RefCell 借用共享状态的一个或多个服务结构、带导出方法的 #[service] impl 块,以及带 init 和暴露服务的 #[program] impl。以小型计数器为例,导出方法可以是 add(value: u32) -> u32、sub(value: u32) -> u32 和 value() -> u32,事件可以是 Added(u32) 和 Subtracted(u32),并在示例修改整数时指出下溢或上溢风险。
服务与状态方面,应按职责而非偶然因素拆分服务,例如将用户操作与管理员或配置操作分开。良好模式包括:把共享合约数据放在一个状态结构中,将 &RefCell<State> 传入每个服务,保持导出 API 窄且领域特定,为多个方法共用的检查使用 ensure_admin(...) 或 ensure_not_paused(...) 等辅助守卫,使用显式读取方法而不是假设调用者能检查内部状态,为客户端需要观察的重要状态转换发出事件,并避免全局可变状态,除非是最小的教学示例。
错误与结果方面,对调用者应看到的业务错误使用 #[export(unwrap_result)],例如存款余额不足、调用者不是管理员、合约已暂停;对于正常合约流程中不可能发生的内部失败,才使用直接 panic 或 expect(...)。
Payable 方法方面,对于启用 ethexe 特性的 Vara.eth 合约,只有当构造函数或导出方法必须随传入消息接收正值时才标记为 payable,使用 #[export(payable)] 或与结果解包组合的 #[export(payable, unwrap_result)]。不要将方法标记为 payable,除非正值传入是其公开 API 的一部分;不要假设导出方法默认 payable;在 ethexe 路径中,如果向非 payable 方法或构造函数发送值,执行将 panic;也不要在 payable 方法内添加冗余的 value == 0 守卫,因为 #[export(payable)] 已表示方法以 value > 0 调用。
公开类型方面,需要区分两类关注点:IDL 友好的公开类型和 Solidity ABI 友好的公开类型。对于 Sails IDL 生成,公开输入和输出类型应可编码、可内省,并足够简单以便生成客户端。对于 Solidity 工具链,公开类型需要额外检查:面向 ABI 的表面必须与当前 ethexe Solidity 生成路径兼容。计划 Solidity 集成时,应尽早运行 cargo sails sol --idl-path ...。当前路径的已知说明包括:u8 在当前 ethexe Solidity 路径上不可用;i8、Vec<u8> 和 String 在当前 ethexe Solidity 路径上可用;对于标识账户的事件字段,应选择当前 ethexe 构建和 Solidity 生成路径验证过的类型,例如 vault 示例中 [u8; 32] 可干净编译用于账户标识符;如果 cargo sails sol 在程序声明形如 program <Name>.opt { ... } 的 IDL 上失败,则用 cargo sails idl --program-name <NameWithoutDot> 重新生成 IDL。常见 ABI 摩擦点包括 HashMap 或 BTreeMap 等映射、深层嵌套的枚举或元组、高度泛型的公开签名、在公开方法中直接暴露内部程序特定类型。对于面向 Solidity 的 API,需要明确 ActorId 与 Ethereum 地址的区别:ActorId 为 32 字节,Ethereum 地址为 20 字节,转换可能需要填充或显式映射规则。
ethexe 运行时限制方面,应从一开始就围绕这些限制进行设计。禁止使用运行时随机性、在程序内创建另一个程序、msg_send_with_gas、msg_reply_with_gas 或其他 *_with_gas 辅助函数或包装器、gas 预留或取消预留流程、基于预留的发送或回复提交流程、signal 系统调用、基于 wait 的普通阻塞行为、延迟唤醒流程。需要标记暗示这些被禁止运行时系统调用的模式,包括 random、create_program、reserve_gas、unreserve_gas、system_reserve_gas、reply_deposit、reservation_send_commit、reservation_reply_commit、signal_from、signal_code、gr_wait。应优先采用显式消息驱动状态机、确定性逻辑和外部编排的工作流。
构建与测试方面,使用 cargo build --release 和 cargo test --release。预期产物位于 target/wasm32-gear/release/ 下,包括 <program>.idl、<program>.wasm 和 <program>.opt.wasm。在宣布合约就绪之前,需确认 .idl 和 .opt.wasm 文件存在。
参考资料方面,最终合约审查清单见 ../../references/contract-writing-checklist.md;当合约声明依赖部署、ABI、RPC、CLI 或运行时实现行为时,阅读 ../../references/source-map.md。