使用

Walrus 提供了 3 种与 Walrus 存储系统直接交互的方式：

通过 Walrus CLI交互
通过 Walrus CLI 的JSON API
通过公共HTTP API或是本地守护进程API

CLI 使用

可通过walrus info查看 Walrus 系统相关信息：

Walrus system information
Current epoch: 0

Storage nodes
Number of nodes: 10
Number of shards: 1000

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

Approximate storage prices per epoch
Price per encoded storage unit: 50 MIST
Price to store metadata: 0.0031 SUI
Marginal price per additional 1 MiB (w/o metadata): 241,950 MIST

Total price for example blob sizes
16.0 MiB unencoded (135 MiB encoded): 0.0069 SUI per epoch
512 MiB unencoded (2.33 GiB encoded): 0.122 SUI per epoch
13.3 GiB unencoded (60.5 GiB encoded): 3.174 SUI per epoch

在 Walrus 上存储 blob 可以通过以下命令来实现：

walrus store <some file> --epochs <EPOCHS>

后面的参数不填默认仅存储一个 epoch,具体一个epoch多长，官方声明目前在 Walrus devnet epoch是固定的，会一直存储，但未来在主网，需要根据你希望访问数据的周期数量付费。

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

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

试着上传一些文件：

先上传个小文件：
再传个大的图片：

可以发现 Walrus在存储非常小的 blob（比如几个字节）不如图片大小的 blob 高效。

但是你多次上传同一份文件，Walrus不会再次上传文件：

stroe_3

还可以使用walrus read <some blob ID>来读取文件内容：

store_4

当然在命令行只能显示文本类文件内容，比如图片视频等格式则需要根据其文件类型专门设置才能显示，比如这个官方的HTMl上传文件的Example，可以在页面上显示上传的图片。

CLI JSON 使用

存储：

walrus json \
    '{
        "config": "path/to/client_config.yaml",
        "command": {
            "store": {
                "file": "README.md"
            }
        }
    }'

读取：

walrus json \
    '{
        "config": "path/to/client_config.yaml",
        "command": {
            "read": {
                "blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo"
            }
        }
    }'

HTTP API 使用

本地启动守护进程

使用以下命令设置本地守护进程：

walrus daemon -b "127.0.0.1:31415"

或者在不同的地址/端口上分别运行聚合器和发布器进程:

walrus aggregator -b "127.0.0.1:31415" # run an aggregator to read blobs
walrus publisher -b "127.0.0.1:31416" # run a publisher to store blobs

💡 提示： 如果在服务器上部署进程，需要注意设置访问权限，aggregator虽然不消耗gas，publisher需要链上操作，是消耗gas的。

浏览器访问守护进程的接口文档：

daemon

公共HTTP API 使用

对于某些用例（例如，公共网站），或者只是尝试 HTTP API，需要可公开访问的聚合器和/或发布者。Walrus提供了公开访问的API：

在本地尝试上传：

AGGREGATOR=https://aggregator.walrus-testnet.walrus.space
PUBLISHER=https://publisher.walrus-testnet.walrus.space

curl -X PUT "$PUBLISHER/v1/store" -d "hello walrus" # store the string `some string` for 1 storage epoch
{
    "newlyCreated": {
        "blobObject": {
            "id": "0x1edf7f949d3a54b83d192ad1cb80f6ef19a09e741bdbeb7b3459f554377dea17", 
            "storedEpoch": 0, 
            "blobId": "HCyYpGgTIU4_mQHGkYpvhcmYa8F79XKeKtXQpo1qoss", 
            "size": 12, 
            "erasureCodeType": "RedStuff", 
            "certifiedEpoch": 0, 
            "storage": {
                "id": "0x3c90e6c9fd5fbada3ed5fb89dd8e92711f391644e43299a17f8d7d7a252d152b", 
                "startEpoch": 0, 
                "endEpoch": 1, 
                "storageSize": 65023000
            }
        }, 
        "encodedSize": 65023000, 
        "cost": 3175000
    }
}
curl -X PUT "$PUBLISHER/v1/store?epochs=5" --upload-file "hello sui" # store file `some/file` for 5 storage epochs

返回的blobId可以在 Sui浏览器上查看:

分析上传的交互细节

首先调用System合约的system模块的reserve_space函数拿到预留存储空间和消耗的Coin：

/// Allow buying a storage reservation for a given period of epochs.
    public fun reserve_space<WAL>(
        self: &mut System<WAL>,
        storage_amount: u64,
        periods_ahead: u64,
        mut payment: Coin<WAL>,
        ctx: &mut TxContext,
    ): (Storage, Coin<WAL>) {}

再调用System合约的blob模块的derive_blob_id函数派生出blob id，当然这步没有在合约细节中显示，我猜测 Walrus 也可以在链下解析文件并派生出blob id（有大佬有别的理解可以联系我交流呀^ _ ^）

/// Derive the blob_id for a blob given the root_hash, erasure_code_type and size.
    public fun derive_blob_id(
      root_hash: u256, 
      erasure_code_type: u8, 
      size: u64): u256 {}

再调用System合约的blob模块的register函数拿到Blob对象

/// Register a new blob in the system.
    /// `size` is the size of the unencoded blob. The reserved space in `storage` must be at
    /// least the size of the encoded blob.
    public fun register<WAL>(
        sys: &System<WAL>,
        storage: Storage,
        blob_id: u256,
        root_hash: u256,
        size: u64,
        erasure_code_type: u8,
        ctx: &mut TxContext,
    ): Blob {}

这里传入的blob_id是u256格式的：

store_5

可以通过一些转换工具来转换下格式，或者直接呼叫AI执行也可以。

 1. Convert u256 to little endian hexadecimal:     50181912741839464529955351348880556819450364832323162298055522980540262911409 -> b10d8c855635c60fc863a1a3ae7339d25d4c3f6c5a2e0d284988f1f3c1f4f16e

 2. convert hex to url-safe base64 with no padding: 
  b10d8c855635c60fc863a1a3ae7339d25d4c3f6c5a2e0d284988f1f3c1f4f16e -> sQ2MhVY1xg_IY6GjrnM50l1MP2xaLg0oSYjx88H08W4

Walrus 官方也认为这样太麻烦，会在未来在CLI中添加对 blob ID 使用u256格式的支持。

最后调用System合约的blob模块的certify函数做认证签名，到这一步，文件就算是在Walrus的服务器在设置的epoch阶段内可访问了。

/// Certify that a blob will be available in the storage system until the end epoch of the
    /// storage associated with it.
    public fun certify<WAL>(
        sys: &System<WAL>,
        blob: &mut Blob,
        signature: vector<u8>,
        members: vector<u16>,
        message: vector<u8>,
    ) {}

使用

CLI 使用​

CLI JSON 使用​

HTTP API 使用​

本地启动守护进程​

公共HTTP API 使用​

分析上传的交互细节​