CosmWasm Plus

开源许可下的实用型智能合约

规范	Crates.io	文档	覆盖率
cw1
cw3
cw4
cw20

合约	下载	文档	覆盖率
cw1-subkeys	Release v0.13.4
cw1-whitelist	Release v0.13.4
cw3-fixed-multisig	Release v0.13.4
cw3-flex-multisig	Release v0.13.4
cw4-group	Release v0.13.4
cw4-stake	Release v0.13.4
cw20-base	Release v0.13.4
cw20-ics20	Release v0.13.4

这是一组专为实际场景设计的规范和合约集合。它们旨在作为解决现实世界用例的示例，并提供可复用的基础，以便构建各种自定义合约。

如果您不了解 CosmWasm，请访问我们的官网和文档以获取更多背景信息。

规范说明

最具复用性的组件是 packages 目录下的各类 cwXYZ 规范。每一项规范都针对不同领域定义了一套标准接口，例如，cw20 适用于 fungible tokens（同质化代币），cw721 适用于 non-fungible tokens（非同质化代币），cw1 适用于“代理合约”等。这些接口不仅在 README 文件中配有详细的文字说明，还提供了可导入使用的 Rust 类型定义。

这些规范本身不包含任何业务逻辑，仅定义接口。它们明确了创建兼容合约时需要实现的内容，同时也向此类合约的所有使用者保证了接口的一致性。这正是规范的核心价值所在——我们可以开发一个托管合约，使其能够处理多种不同的同质化代币，前提是这些代币都遵循 cw20 规范。

如果您有新规范的想法，请在本仓库提交 issue 或创建 pull request。

合约示例

我们提供了一系列示例合约，这些合约要么实现了上述规范，要么使用了这些规范。它们不仅作为示例展示规范的应用，还为您开发更定制化的合约提供了可扩展的代码基础，让您无需每次都从零开始。例如，cw20-base 就是一个符合 cw20 规范的基础实现合约，您可以在构建自定义合约时直接导入使用。

CW1 代理合约：

• cw1-whitelist：cw1 的最小化实现，主要用于参考。
• cw1-subkeys：一个简单但实用的实现。它允许我们使用代理合约来为原生代币提供“额度允许”功能，而无需修改 bank 模块。

CW3 多签合约：

• cw3-fixed-multisig：cw3 规范 的简单实现。它是一种多签合约，拥有在初始化时确定的固定地址集。每个地址可以拥有相同的权重（N 中取 K），也可以有部分地址拥有额外的投票权。其工作方式与 Cosmos SDK 原生的多签机制类似，不同之处在于，它是在链上聚合审批，而非链下聚合签名后提交最终结果。
• cw3-flex-multisig：在 cw3-fixed-multisig 的基础上构建，是 cw3 规范的更强大实现。它是一个由 cw4（群组）合约支持的多签合约，该 cw4 合约独立维护投票者集合。

CW4 群组合约：

• cw4-group：cw4 规范 的基础实现。它通过管理员或多签合约来管理选举成员。该合约满足规范的所有要求，包括原始查询查找，并设计用作 cw3 兼容合约 的后端存储。
• cw4-stake：cw4 规范 的另一种实现。它同样满足规范的所有要求，包括原始查询查找，并设计用作 cw3 兼容合约 的后端存储。它提供与 [cw4-group] 类似的 API，但成员资格及其权重并非通过任命方式确定，而是基于成员质押的代币数量。

CW20 同质化代币：

• cw20-base：一个简洁而完整的 cw20 规范实现，包含所有扩展功能。既可以直接部署使用，也可以被其他合约导入。

编译

若要编译所有合约，请在仓库根目录中运行以下命令：

docker run --rm -v "$(pwd)":/code \
  --mount type=volume,source="$(basename "$(pwd)")_cache",target=/target \
  --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
  cosmwasm/optimizer:0.16.0

这将编译 contracts 目录中的所有软件包，并在 artifacts 目录下输出经过剥离和优化的 wasm 代码，同时生成一个 checksums.txt 文件。

如果在此过程中遇到任何问题并需要调试，可以尝试在每个合约目录中运行以下命令： RUSTFLAGS="-C link-arg=-s" cargo build --release --target=wasm32-unknown-unknown --locked

质量控制

代码质量保障的基本指标之一是单元测试的覆盖率。Rust 有多种工具可用于此类分析，下面将介绍其中一种。这应作为基准指标，为代码提供一定程度的信心。

除了代码覆盖率指标外，建立健全的 PR 审查流程，让更多训练有素的人员参与寻找漏洞，对于发现原开发者未意识到的问题路径非常有帮助。这虽然更为主观，但查看相关 PR 以及讨论的深度，可以了解审查的充分程度。

在此基础上，进行模糊测试（理想情况下使用了解相关领域的智能模糊测试工具）会很有价值。更进一步，形式化验证可以提供更高的保障（但非常耗时且成本高昂）。

代码覆盖率

我推荐使用 tarpaulin：cargo install cargo-tarpaulin

要生成一些直观的交互式图表，你可以进入根目录并运行：

cargo tarpaulin -o html，然后运行 xdg-open tarpaulin-report.html（在 macOS 上只需使用 open）。

当你发现某个软件包需要改进时，可以按以下方式仅分析该软件包，从而加快反馈速度：

cargo tarpaulin -o html --packages cw3-fixed-multisig

请注意，它会生成整个项目的代码覆盖率报告，但只有该软件包内的覆盖率才是真正有价值的。这能快速反馈你的单元测试编写是否成功。

贡献

请参阅我们的贡献指南。

生成变更日志

为了生成变更日志，我们决定使用 github-changelog-generator。

安装此工具需要 Ruby 的 gem 包管理器。

$ gem --user install github_changelog_generator

并将 $HOME/.gem/ruby/*/bin/ 添加到你的 PATH 中。

首次生成变更日志文件：

$ github_changelog_generator -u CosmWasm -p cw-plus

追加后续版本可通过添加 --base 标志实现：

$ github_changelog_generator -u CosmWasm -p cw-plus --base CHANGELOG.md

如果遇到 GitHub 的每小时 50 次请求限制，请按照 此 指南创建一个令牌密钥，你可以使用 --token 标志传递该密钥。

此外，还有一个便捷的脚本 scripts/update_changelog.sh，它可以接受 --since-tag 参数（以避免处理整个历史记录）。它还可以通过 --latest-tag 为你自动检测最新的版本标签。

许可证

本仓库采用 Apache 2.0 许可证。