Soldeer

Soldeer 是一个用 Rust 构建的 Solidity 包管理器。

Solidity 开发变得越来越复杂。对包管理器的需求变得显而易见。 这个项目旨在解决以下问题：

• foundry 中的 git 子模块不是管理依赖项的好方法
• npmjs 是为 js 生态系统构建的，不适用于 solidity
• GitHub 版本发布管理很麻烦，而且并非所有项目都正确使用它

版本 0.3.0

版本 0.3.0 引入了以下重大变更

配置文件

配置文件（在 foundry.toml 和 soldeer.toml 之间任何包含 [dependencies] 表的文件）现在有一个 [soldeer] 部分，格式和默认值如下：

[soldeer]
# soldeer 是否管理重映射
remappings_generated = true

# 安装、更新或卸载依赖项时，soldeer 是否重新生成所有重映射
remappings_regenerate = false

# 是否在重映射后缀中添加版本号：`name-a.b.c`
remappings_version = true

# 添加到重映射前缀（"@" 会生成 `@name`）
remappings_prefix = ""

# 存储重映射的位置（"txt" 表示 `remappings.txt`，"config" 表示 `foundry.toml`）
# 当使用 `soldeer.toml` 作为配置时忽略（使用 `remappings.txt`）
remappings_location = "txt"

# 是否安装子依赖项。如果为 true，将安装依赖项的依赖项，深度为 1 级。
recursive_deps = false

重映射

完全可配置的重映射，查看 重映射。

警告：测试版 - 使用风险自负

Soldeer 有 3 个部分：

• soldeer cli - 独立工具，可用于管理项目依赖项，独立运行且不依赖于 foundry
• soldeer 仓库 - 用于存储各种包的中央仓库。任何人都可以将自己的包作为公共包推送。该仓库的工作方式类似于 npmjs 或 crates.io
• soldeer foundry - 一个 foundry 插件，允许你直接在 foundry 项目中使用 soldeer：forge soldeer [命令]

如何使用

Soldeer CLI

Soldeer cli 是一个独立工具，可用于管理项目中的依赖项。它不依赖于 foundry，可以在任何项目中使用。 cli 也可以与 foundry 一起使用，通过在名为 dependencies 的新目录中安装依赖项，并可用于更新 remappings.txt 文件中的重映射。

要使用 cli，你需要通过 cargo 安装：

cargo install soldeer

上述命令会将 soldeer 安装到你的 ~/.cargo/bin 文件夹中。确保它已添加到你的 PATH 中（通常已经添加）。

然后你需要在项目根目录创建一个 soldeer.toml 文件。文件应该如下所示：

[remappings]
enabled = true

[dependencies]

remappings 选项允许你启用或禁用重映射自动补全。如果设置为 true，则在安装新依赖项时会自动更新重映射。 dependencies 选项用于存储通过 soldeer install <dependency>~<version> 命令安装的依赖项。

如果你想与 foundry 一起使用，可以跳过创建 soldeer.toml 文件，直接使用 foundry.toml 文件。你只需要在 foundry.toml 文件中添加 dependencies 选项，重映射将自动更新。

foundry 配置示例：

[profile.default]
auto_detect_solc = false
bytecode_hash = "none"
cbor_metadata = false

.... 其他 foundry 配置
[dependencies]

即使 [dependencies] 为空，这也会告诉 soldeer 使用 foundry.toml 文件进行依赖项管理。

警告

如果你没有定义带有 enabled 字段的 soldeer.toml 或带有 dependencies 字段的 foundry.toml，重映射将不会更新，你会收到一个警告。

如何安装

cargo install soldeer

检查安装是否成功

soldeer help

从源代码安装

cargo build --release 并使用 target/release/ 中的 soldeer 二进制文件。

如何使用

Soldeer 使用简单。它可以与 foundry.toml 文件配合使用，或者你可以创建一个 soldeer.toml。从 0.1.5 版本开始，如果你只想使用 foundry.toml 文件，可以跳过创建 soldeer.toml。

依赖项安装

使用以下命令初始化新安装。它将生成一个 foundry.toml 或 soldeer.toml 文件，其中包含最新版本的 forge-std。此命令主要用于将 Soldeer 集成到你的 Foundry 项目中，或用 Soldeer 的设置替换旧的 Foundry 设置。使用 --clean true 参数，你可以删除旧的 .gitmodules 文件和 lib 目录。

soldeer init

通过以下方式添加依赖项

soldeer install <dependency_name>~<version>

要搜索依赖项是否可用，请访问 https://soldeer.xyz。

此外，你还可以从任何 URL 上的 zip 文件安装依赖项：

soldeer install <dependency_name>~<version> <url>

此命令将下载依赖项的 zip 文件，解压缩，并将其安装在 dependencies 目录中。

soldeer install

此命令将安装 soldeer.toml/foundry.toml 文件中的所有依赖项。

如何将新依赖项推送到仓库

要将新依赖项推送到仓库，你需要在 https://soldeer.xyz 上创建一个账户，创建一个与依赖项名称匹配的项目。

示例： 创建一个名为 my-project 的项目，然后使用 soldeer push my-project~v1.0。这将把项目推送到仓库，供所有人使用。 在使用 push 命令之前，你必须使用 soldeer login 登录到仓库。

推送特定目录

如果你想推送项目中的特定目录，可以使用 soldeer push my-project~v1.0 /my/path/to/source/files 选项。这将只推送指定目录中的文件。

忽略文件

如果你想在推送时忽略某些文件，需要创建一个 .soldeerignore 文件，其中包含要忽略的文件。该文件应位于项目根目录。这个文件模仿 .gitignore 语法。

试运行

如果你想进行推送的试运行以检查将推送到中央仓库的文件，请使用 soldeer push my-project~v1.0 [PATH_TO_DEPENDENCY] --dry-run true。这将创建一个 zip 文件，你可以解压缩并检查推送的内容。我们建议每个人在推送新依赖项之前运行试运行，以避免推送不需要的文件。

重映射

重映射现在完全可配置，foundry/soldeer TOML 文件接受一个 [soldeer] 字段，具有以下选项

[soldeer]
# soldeer 是否管理重映射
remappings_generated = true

# 安装、更新或卸载依赖项时，soldeer 是否重新生成所有重映射
remappings_regenerate = false

# 是否在重映射后缀中添加版本号：`name-a.b.c`
remappings_version = true

# 添加到重映射前缀（"@" 会生成 `@name`）
remappings_prefix = ""

# 存储重映射的位置（"txt" 表示 `remappings.txt`，"config" 表示 `foundry.toml`）
# 当使用 `soldeer.toml` 作为配置时忽略（使用 `remappings.txt`）
remappings_location = "txt"

# 是否安装子依赖项。如果为 true，将安装依赖项的依赖项，深度为 1 级。
recursive_deps = false

安装依赖项的依赖项

每当你安装一个依赖项时，该依赖项可能还需要安装其他依赖项。目前，你可以在[soldeer]部分将recursive_deps字段设置为true，或者在调用install或update时传递--recursive-deps参数。这将触发安装过程进入依赖项内部，并运行git submodule update和soldeer install。通过执行这些命令，依赖项将拉取其正常运行所需的所有必要依赖项。

当前存在的问题

依赖项的依赖项目前存在的问题是，由于重映射不当，某些依赖项可能无法正常运行。例如：

我们有一个名为my-project的项目，它有以下依赖项：

• dependency-1
• openzeppelin-5.0.2

my-project中的一个合约有以下导入：

@openzeppelin/contracts/token/ERC20/ERC20.sol

然而，dependency-1也需要openzeppelin，但它使用的是4.9.2版本。dependency-1中的合约有相同的导入：

@openzeppelin/contracts/token/ERC20/ERC20.sol

由于合约文件中的重映射不当，这种情况会造成如上所述的歧义。为了解决这个问题，我们应该开始在导入中使用版本控制，例如：

import from 'openzeppelin-4.9.2/token/ERC20/ERC20.sol';

这种方法将允许我们有效地处理各种依赖项的多个版本。

完整的命令列表

更多命令请使用soldeer help。

Foundry集成

一旦完成Foundry集成，你将能够直接从Foundry中使用soldeer，方法是使用forge soldeer ...。 你将拥有与独立版本相同的命令。

注意事项

"添加到重映射"功能只是附加到remappings.txt文件，不会删除旧的依赖项。如果你想从重映射中删除依赖项，必须手动操作。

如果你使用其他依赖管理器，如git子模块或npm，请确保不要在soldeer和其他管理器之间重复依赖项。

依赖项维护

Soldeer的目标是集成到每个开源项目的流程中，如OpenZeppelin、Solady、Uniswap等。这些项目的维护者可以将自己的依赖项推送到仓库，社区可以使用它们。在此之前，Soldeer维护团队（目前是m4rio.eth）将通过依赖npmjs版本或GitHub来将最常用的依赖项推送到仓库。我们使用这个软件来爬取并将依赖项推送到soldeer组织下。

对于那些想要额外安全层的人，在soldeer.lock文件中为安装的依赖项生成了SHA。一些项目被截断了，例如，对于OpenZeppelin，只有contracts目录被推送到仓库，所以你需要将SHA与原始版本的contracts目录进行对比。

对于项目维护者 如果你想将你的项目从Soldeer组织转移出来，并自己负责将版本推送到Soldeer，请开一个issue或在X（原Twitter）上联系我。

版本0.2.19引入以下重大变更

现在你可以使用git安装依赖项。支持的平台：github和gitlab。 目前，我们只支持公共仓库。

语法是soldeer install <dependency>~<version> <git-url>。这将克隆仓库并在dependencies文件夹中安装依赖项。

你也可以使用某个特定的提交作为依赖项

soldeer install <dependency>~<version> git:<url> <commit>

一些例子

soldeer install test-project~v1 git@github.com:test/test.git
soldeer install test-project~v1 git@gitlab.com:test/test.git

soldeer install test-project~v1 https://github.com/test/test.git
soldeer install test-project~v1 https://gitlab.com/test/test.git

或使用自定义提交哈希

soldeer install test-project~v1 git@github.com:test/test.git --rev 345e611cd84bfb4e62c583fa1886c1928bc1a464

版本0.2.7引入以下重大变更

将依赖项键保存为依赖项名称，以遵循Cargo.toml格式。对于同一依赖项的多个版本，已创建一个问题作为功能添加#34。目前，依赖项名称是toml文件中的键。

0.2.6版本引入的重大变更

在0.2.6中，sdependencies已重命名为dependencies。此外，现在存储在toml中的依赖项遵循Cargo toml格式，包含version和url。