Using the Walrus client

walrus 二进制文件可用作客户端与 Walrus 进行交互。有关先决条件、安装和配置，请参阅 设置章节。

详细的使用信息可以通过以下方式获得

walrus --help

walrus 的每个子命令也可以使用 --help 调用，以打印其特定参数及其含义。

Walrus system information

有关 Walrus 系统的信息可以通过 walrus info 命令获得。例如，walrus info 提供了系统中存储节点和分片的数量概述、最大 blob 大小以及存储 blob 的当前 (Testnet) WAL 成本：

$ walrus info

Walrus system information
Current epoch: 2

Storage nodes
Number of nodes: 25
Number of shards: 1000

Blob size
Maximum blob size: 13.3 GiB (14,273,391,930 B)
Storage unit: 1.00 MiB

Approximate storage prices per epoch
Price per encoded storage unit: 100 FROST
Price to store metadata: 6,200 FROST
Marginal price per additional 1 MiB (w/o metadata): 500 FROST

Total price for example blob sizes
16.0 MiB unencoded (135 MiB encoded): 13,500 FROST per epoch
512 MiB unencoded (2.33 GiB encoded): 0.0002 WAL per epoch
13.3 GiB unencoded (60.5 GiB encoded): 0.0062 WAL per epoch

FROST and WAL

FROST is the smaller unit of WAL, similar to MIST for SUI. The conversion is also the same as for SUI: 1 WAL = 1 000 000 000 FROST.

其他信息，如编码参数和大小、BFT 系统信息以及存储节点及其分片分布的信息，可以使用 --dev 参数查看：walrus info --dev。

存储、查询状态和读取 blob

Public access

All blobs stored in Walrus are public and discoverable by all. Therefore you must not use Walrus to store anything that contains secrets or private data without additional measures to protect confidentiality.

Warning

It must be ensured that only a single process uses the Sui wallet for write actions (storing or deleting). When using multiple instances of the client simultaneously, each of them must be pointed to a different wallet.

Obtaining Testnet WAL

You can exchange Testnet SUI for Testnet WAL by running walrus get-wal. See the setup page for further details.

Storing blobs on Walrus can be achieved through the following command:

walrus store <some file>

store 命令接受一个 CLI 参数 --epochs <EPOCHS>（或 -e），指示 blob 应存储的 epoch 数量。默认值为 1 个 epoch，即当前 epoch。

Automatic optimizations

When storing a blob, the client performs a number of automatic optimizations, including the following:

  • If the blob is already stored as a permanent blob on Walrus for a sufficient number of epochs the command does not store it again. This behavior can be overwritten with the --force (or -f) CLI option, which stores the blob again and creates a fresh blob object on Sui belonging to the wallet address.
  • If the user's wallet has a compatible storage resource, this one is (re-)used instead of buying a new one.
  • If the blob is already certified on Walrus but as a deletable blob or not for a sufficient number of epochs, the command skips sending data to the storage nodes and just collects the availability certificate

可以通过以下命令之一查询 blob 的状态：

walrus blob-status --blob-id <BLOB_ID>
walrus blob-status --file <FILE>

这将返回 blob 是否已存储及其可用期。如果使用 --file 选项指定文件，CLI 将重新编码文件内容并在检查状态之前派生 blob ID。

当 blob 可用时，blob-status 命令还会返回 BlobCertified Sui 事件 ID，该 ID 由交易 ID 和交易发出的事件中的序列号组成。此事件的存在证明了 blob 的可用性。

可以通过以下命令从 Walrus 读取 blob：

walrus read <some blob ID>

默认情况下，blob 数据写入标准输出。可以使用 --out <OUT> CLI 选项（或 -o）指定输出文件名。可以使用 --rpc-url <URL>（或 -r）指定要使用的 Sui RPC 节点，而不是钱包配置中设置的节点或默认节点。

通过可删除的 blob 回收空间

默认情况下，walrus store 上传一个 blob，Walrus 会在其到期纪元之后保持其可用性。即使是上传者也不能提前删除它。但是，可以选择使用 --deletable 标志调用 store 命令，以指示 blob 可以在其到期之前由表示该 blob 的 Sui blob 对象的所有者删除。可删除的 blob 在证明它们的 Sui 事件中被如此标示，不应依赖其他人来保证其可用性。

可以使用以下命令删除可删除的 blob：

walrus delete --blob-id <BLOB_ID>

可以选择通过指定 --file <PATH> 选项来调用 delete 命令，从文件中派生 blob ID，或 --object-id <SUI_ID> 删除指定的 Sui blob 对象中的 blob。

delete 命令回收与已删除 blob 关联的存储对象，该对象被重新用于存储新 blob。删除操作在管理存储成本和重新使用存储方面提供了灵活性。

删除操作对隐私的作用有限：它只删除当前纪元存储节点和后续纪元存储节点中的碎片，如果没有其他用户上传相同 blob 的副本。如果 Walrus 中存在相同 blob 的另一个副本，删除操作不会使该 blob 无法下载，并且 walrus read 调用将下载它。公共 blob 的副本可能会被用户缓存或下载，这些副本不会被删除。

Delete reclaims space only

All blobs stored in Walrus are public and discoverable by all. The delete command will not delete slivers if other copies of the blob are stored on Walrus possibly by other users. It does not delete blobs from caches, slivers from past storage nodes, or copies that could have been made by users before the blob was deleted.

Blob ID 工具

walrus blob-id <FILE> 可用于派生任何文件的 blob ID。blob ID 是对文件的承诺，任何具有相同 ID 的 blob 都将解码为相同的内容。blob ID 是一个 256 位数字，在某些 Sui explorer 上表示为十进制大数字。命令 walrus convert-blob-id <BLOB_ID_DECIMAL> 可用于将其转换为命令行工具和其他 API 使用的 base64 URL 安全编码。

walrus list-blobs 命令列出当前帐户拥有的所有未过期的 Sui blob 对象，包括它们的 blob ID、对象 ID 以及有关到期和可删除状态的元数据。选项 --include-expired 还会列出已过期的 blob 对象。

更改默认配置

使用 --config 选项指定 配置位置 的自定义路径。

--wallet <WALLET> 参数可用于指定非标准 Sui 钱包配置文件。--gas-budget <GAS_BUDGET> 参数可用于更改命令允许使用的最大 Sui 数量（以 MIST 为单位）。