开发区块链智能合约（尤其…

适用于基于 CosmWasm/Cosmos 开发区块链智能合约、处理 IBC 跨链消息并需要测试、审计和文档化的场景。

适用场景

解决思路

1. 在安全性与正确性优先于过早优化：先保证合约安全、逻辑正确，再考虑性能优化。
2. 面向不可变性和确定性执行进行设计：避免依赖非确定性来源，确保相同输入得到相同结果。
3. 实施完整测试与审计实践：为合约逻辑建立测试覆盖，并在重要版本安排审计。
4. 遵循目标区块链生态的既有模式：使用该生态推荐的合约结构、消息流和安全约定。
5. 使用 Rust 类型系统提供安全保障：用枚举、泛型、类型状态等表达不变量，减少非法状态。
6. 利用 CosmWasm 合约模型进行状态管理：通过合约存储和消息驱动的方式管理状态变更。
7. 实现正确入口点 instantiate、execute、query：分别实现初始化、执行和查询入口。
8. 使用自定义错误类型显式处理错误：定义合约专属错误类型，并在各入口返回或传播错误。
9. 遵循 IBC 协议标准进行跨链通信：按 IBC 规范实现端口、通道、数据包和确认流程。
10. 实现正确的 packet handling 和 acknowledgments：处理数据包接收、确认、错误确认和响应。
11. 在开发中与多条链进行测试：搭建多链本地或测试网环境，验证跨链交互。
12. 优雅处理 timeout 场景：在超时后安全回滚、补偿或释放资源，避免状态不一致。
13. 使用高效存储模式（Item、Map、IndexedMap）：按查询、索引和遍历需求选择对应存储结构。
14. 为 gas 效率最小化存储操作：减少不必要的读写、遍历和重复写入，必要时缓存或合并操作。
15. 实现正确的升级迁移路径：编写 migrate 入口和状态迁移逻辑，保证升级后状态兼容。
16. 设计幂等消息处理器：对重复消息使用唯一 ID、状态位或去重表，避免重复副作用。
17. 实现重放保护：使用 nonce、sequence、消息 ID 等机制防止跨链消息被重放。
18. 优雅处理部分失败：记录已成功和失败的步骤，支持重试、补偿或人工恢复。
19. 记录所有跨链操作：对跨链消息、确认、超时和失败写入日志或事件。
20. 验证所有传入消息：校验来源链、通道、发送者、格式、权限、金额和业务约束。
21. 实现正确的访问控制：使用 owner、admin、role 等机制限制敏感入口。
22. 对敏感操作使用时间锁定：通过 timelock 或延迟执行窗口降低误操作和攻击风险。
23. 监控异常活动模式：对异常频率、金额、失败率或调用路径设置告警和监控。
24. 为所有合约逻辑编写单元测试：覆盖每个 execute、query 分支和错误路径。
25. 使用模拟区块链状态进行集成测试：在模拟链状态下测试合约间交互和状态变化。
26. 对边界情况进行模糊测试：用 fuzz testing 覆盖随机输入、极端值和异常路径。
27. 主网部署前进行安全审计：上线前完成安全审计并修复发现的问题。
28. 文档化所有公共接口：说明消息、查询、参数、返回值和错误类型。
29. 维护部署和升级指南：记录部署步骤、网络参数、升级流程和回滚方案。
30. 保留架构决策记录：记录关键设计选择、权衡原因和后续影响。
31. 提供清晰的集成示例：给出客户端调用、跨链集成或合约交互的可运行示例。

适用边界 · 注意事项

• 不涉及区块链、智能合约或跨链通信的普通应用开发。
• 目标链不是 Cosmos/CosmWasm 生态，或不使用 IBC 协议时，CosmWasm 和 IBC 相关做法不直接适用。
• 仅做一次性本地原型且不部署主网、无跨链需求时，可简化审计、迁移和监控等重流程。